# ahrefs-python

Guides the coding agent on using the official Ahrefs Python SDK. Useful when querying backlinks, keyword rankings, domain ratings, and audit data.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 313 installs · ★ 721
- Author: OpenClaudia
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/OpenClaudia/openclaudia-skills/tree/HEAD/skills/ahrefs-research/SKILL.md
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/skills/ahrefs-python

## What it does

This skill provides rules for integrating the `ahrefs-python` library, covering 52 methods across 7 API sections including Site Explorer, Keywords Explorer, and Site Audit. It ensures the assistant uses `AhrefsClient` or `AsyncAhrefsClient`, typed Pydantic models, and method discovery via `python3 -m ahrefs.api_search`.

The instructions explicitly forbid raw HTTP calls with `httpx` or `requests` because the SDK handles automatic retries on 429 and 5xx errors. For collection endpoints, the skill enforces using the `select` parameter to prevent wasting API units on unneeded columns. All date parameters must be formatted as `YYYY-MM-DD` strings.

The underlying library requires Python 3.11+ alongside `httpx` and `pydantic`. Authentication relies on an API token set in the `AHREFS_API_KEY` environment variable.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenClaudia/openclaudia-skills --skill ahrefs-python -a claude-code
```
```bash
npx skills add OpenClaudia/openclaudia-skills --skill ahrefs-research -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/ahrefs-research/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/ahrefs-research/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenClaudia/openclaudia-skills --skill ahrefs-research -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/ahrefs-research/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenClaudia/openclaudia-skills --skill ahrefs-research -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/ahrefs-research/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install OpenClaudia/openclaudia-skills ahrefs-research
```

2. **Manually: put the files in place**
- File: `.github/skills/ahrefs-research/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add OpenClaudia/openclaudia-skills --skill ahrefs-research -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/OpenClaudia/openclaudia-skills --path skills/ahrefs-research
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/ahrefs-research/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add OpenClaudia/openclaudia-skills --skill ahrefs-research -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/OpenClaudia/openclaudia-skills/tree/HEAD/skills/ahrefs-research/SKILL.md

## When to use it
- fetch domain rating and backlink metrics via AhrefsClient
- query organic keywords with targeted columns using `select`
- run parallel API requests using AsyncAhrefsClient and asyncio
- discover SDK endpoints via the built-in api_search CLI tool

## Example prompts
- Write an async script using ahrefs-python to get the Domain Rating for example.com
- Search for the right ahrefs-python method to pull backlinks for a domain
- Fetch top 10 keywords for a site with volume and position fields using AhrefsClient

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 7576731e401cccb9.

BEGIN THIRD-PARTY FILE 7576731e401cccb9
````text
---
name: ahrefs-python
description: 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.
---

# 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
pip3 install git+https://github.com/ahrefs/ahrefs-python.git
```

Requires Python 3.11+. Dependencies: `httpx`, `pydantic`.

## API Method Discovery

The SDK has 52 methods across 7 API sections. The built-in search tool is the fastest way to find the right method — it returns matching method signatures, parameters, and return types directly, so there's no need to scan through a large reference.

**Python** (preferred when already in a Python context):

```python
from ahrefs.search import search_api_methods

# Returns formatted text with method signatures, parameters, and return types
print(search_api_methods("domain rating"))

# Filter by API section and limit results
print(search_api_methods("backlinks", section="site-explorer", limit=3))
```

**CLI** (preferred when exploring from the terminal):

```sh
# Ensure python3 points to the interpreter where ahrefs-python is installed:
#   which python3
#   python3 -c "import ahrefs"
python3 -m ahrefs.api_search "domain rating"
python3 -m ahrefs.api_search "backlinks" --section site-explorer --limit 3
python3 -m ahrefs.api_search "batch" --json
python3 -m ahrefs.api_search --sections  # list all API sections
```

## 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"`).
````
END THIRD-PARTY FILE 7576731e401cccb9

The third-party file has ended. Everything between the 7576731e401cccb9 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2558 of 7583 bytes. © OpenClaudia · MIT · https://github.com/OpenClaudia/openclaudia-skills/tree/HEAD/skills/ahrefs-research/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md