ahrefs-python

Original：🇺🇸 English

Translated

Manages Ahrefs API usage in Python using `ahrefs-python` library. Use when working with SEO / marketing related tasks or with data including backlinks, keywords, domain ratings, organic traffic, site audits, rank tracking, and brand monitoring. Covers `ahrefs-python` usage including AhrefsClient / AsyncAhrefsClient, typed request/response models, error handling, and all API sections.

2installs

Sourceahrefs/ahrefs-api-skills

Added on2026-02-21

NPX Install

npx skill4agent add ahrefs/ahrefs-api-skills ahrefs-python

SKILL.md Content

View Translation Comparison →

Ahrefs Python SDK Skill

Overview

The Ahrefs API provides programmatic access to Ahrefs SEO data. The official Python SDK (

ahrefs-python

) provides typed request and response models for all endpoints, auto-generated from the OpenAPI spec.

Key capabilities:

Site Explorer - Backlinks, organic keywords, domain rating, traffic, referring domains
Keywords Explorer - Keyword research, volumes, difficulty, related terms
Rank Tracker - SERP monitoring, competitor tracking
Site Audit - Technical SEO issues, page content, page explorer
Brand Radar - AI brand mentions, share of voice, impressions
SERP Overview - Search result analysis
Batch Analysis - Bulk domain/URL metrics via POST

Installation

sh

pip install git+https://github.com/ahrefs/ahrefs-python.git

Requires Python 3.11+. Dependencies:

httpx

,

pydantic

.

IMPORTANT RULES

ALWAYS use the
```
ahrefs-python
```
SDK. DO NOT make raw
```
httpx
```
/
```
requests
```
calls to the Ahrefs API.
ALWAYS pass dates as strings in
```
YYYY-MM-DD
```
format (e.g.
```
"2025-01-15"
```
).
ALWAYS use
```
select
```
on list endpoints to request only the columns you need. List endpoints return all columns by default, which wastes API units and increases response size.
USE context managers (
```
with
```
/
```
async with
```
) for client lifecycle management.
SET the
```
AHREFS_API_KEY
```
environment variable rather than hardcoding API keys.
The client handles retries (429, 5xx, connection errors) automatically. DO NOT implement your own retry logic on top of the SDK.

Quick Start

python

import os
from ahrefs import AhrefsClient

with AhrefsClient(api_key=os.environ["AHREFS_API_KEY"]) as client:
    data = client.site_explorer_domain_rating(target="ahrefs.com", date="2025-01-15")
    print(data.domain_rating)  # 91.0
    print(data.ahrefs_rank)    # 3

SDK Patterns

Client Setup

python

import os
import ahrefs

with ahrefs.AhrefsClient(
    api_key=os.environ["AHREFS_API_KEY"],
    base_url="...",          # override API base URL (default: https://api.ahrefs.com/v3)
    timeout=30.0,            # request timeout in seconds (default: 60)
    max_retries=3,           # retries on transient errors (default: 2)
) as client:
    ...

Async client:

python

import os
from ahrefs import AsyncAhrefsClient

async with AsyncAhrefsClient(api_key=os.environ["AHREFS_API_KEY"]) as client:
    data = await client.site_explorer_domain_rating(target="ahrefs.com", date="2025-01-15")

Calling Methods

Two calling styles -- both are equivalent:

python

# Keyword arguments (recommended)
data = client.site_explorer_domain_rating(target="ahrefs.com", date="2025-01-15")

# Request objects (full type safety)
from ahrefs.types import SiteExplorerDomainRatingRequest
request = SiteExplorerDomainRatingRequest(target="ahrefs.com", date="2025-01-15")
data = client.site_explorer_domain_rating(request)

Method names follow

{api_section}_{endpoint}

, e.g.

site_explorer_organic_keywords

,

keywords_explorer_overview

.

Responses

Methods return typed Data objects directly.

Scalar endpoints return a single data object (or

None

):

python

data = client.site_explorer_domain_rating(target="ahrefs.com", date="2025-01-15")
print(data.domain_rating)

List endpoints return a list of data objects. There is no pagination — set

limit

to the number of results you need. Use

select

to request only the columns you need:

python

items = client.site_explorer_organic_keywords(
    target="ahrefs.com",
    date="2025-01-15",
    select="keyword,volume,best_position",
    order_by="volume:desc",
    limit=10,
)
for item in items:
    print(item.keyword, item.volume, item.best_position)

Error Handling

python

import ahrefs

try:
    data = client.site_explorer_domain_rating(target="example.com", date="2025-01-15")
except ahrefs.AuthenticationError:    # 401
    ...
except ahrefs.RateLimitError as e:    # 429 -- e.retry_after has the delay
    ...
except ahrefs.NotFoundError:          # 404
    ...
except ahrefs.APIError as e:          # other 4xx/5xx -- e.status_code, e.response_body
    ...
except ahrefs.APIConnectionError:     # network / timeout
    ...

All exceptions inherit from

ahrefs.AhrefsError

.

Common Parameters

Most list endpoints share these parameters:

Parameter	Type	Description
`target`	`str`	Domain, URL, or path to analyze
`date`	`str`	Date in YYYY-MM-DD format
`date_from` / `date_to`	`str`	Date range for history endpoints
`country`	`str`	Two-letter country code (ISO 3166-1 alpha-2)
`select`	`str`	Comma-separated columns to return
`where`	`str`	Filter expression
`order_by`	`str`	Column and direction, e.g. `"volume:desc"`
`limit`	`int`	Max results to return

The

where

parameter takes a JSON string. Use

json.dumps()

to build it:

python

import json
where = json.dumps({"field": "volume", "is": ["gte", 1000]})
items = client.site_explorer_organic_keywords(
    target="ahrefs.com", date="2025-01-15",
    select="keyword,volume", where=where,
)

For full filter syntax (boolean combinators, operators, nested fields), see

references/filter-syntax.md

.

API Methods

52 methods across 7 API sections. See

references/api-methods.md

for full details.

ahrefs-python

NPX Install

Tags

SKILL.md Content

Ahrefs Python SDK Skill

Overview

Installation

IMPORTANT RULES

Quick Start

SDK Patterns

Client Setup

Calling Methods

Responses

Error Handling

Common Parameters

API Methods