> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mavera.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Ahrefs

> 4 production-ready jobs — top pages content replication, trending topic discovery, competitive domain positioning, and keyword-driven content at scale

Ahrefs is one of the most comprehensive SEO toolkits available — backlink indexes, keyword databases, content explorers, and site audits all accessible through a single API. These four jobs connect Ahrefs data to Mavera's surfaces (Mave Agent, Personas, Focus Groups, Brand Voices, Generate) so your content strategy, competitive positioning, and SEO execution are driven by real search data rather than guesswork.

<Info>
  All examples use two environment variables: `AHREFS_API_TOKEN` and `MAVERA_API_KEY`. Ahrefs API v3 returns JSON and authenticates via Bearer token (`Authorization: Bearer {token}`) or OAuth 2.0. Every API call consumes at least **50 units** — check your balance at [Ahrefs → API Usage](https://app.ahrefs.com/api/usage). Rate limit is **60 requests per minute**; the API returns `429 Too Many Requests` when exceeded.
</Info>

## API Reference Card

| Detail              | Value                                                       |
| ------------------- | ----------------------------------------------------------- |
| **Base URL**        | `https://api.ahrefs.com/v3/`                                |
| **Auth**            | Bearer Token (`Authorization: Bearer {token}`) or OAuth 2.0 |
| **Rate limits**     | 60 requests/minute                                          |
| **Minimum cost**    | 50 units per request                                        |
| **Response format** | JSON                                                        |
| **Mavera base**     | `https://app.mavera.io/api/v1`                              |
| **Mavera auth**     | `Authorization: Bearer mvra_live_...`                       |

## Prerequisites

<Steps>
  <Step title="Ahrefs API token with available units">Log in to [Ahrefs](https://ahrefs.com/) and navigate to **API** → **API Keys** to generate a token. Verify that your plan includes API access — Starter plans have limited units, while Standard and above include higher allocations.</Step>
  <Step title="Mavera API key">Generate a key at [app.mavera.io/settings/api-keys](https://app.mavera.io/settings/api-keys). The key starts with `mvra_live_`.</Step>

  <Step title="Install dependencies">
    ```bash theme={"dark"}
    pip install requests openai
    ```
  </Step>

  <Step title="Environment variables">
    ```bash theme={"dark"}
    export AHREFS_API_TOKEN="your_ahrefs_api_token_here"
    export MAVERA_API_KEY="mvra_live_xxxxx"
    ```
  </Step>
</Steps>

## Jobs

| # | Job                                                                             | Ahrefs Data                     | Mavera Surface            | Output                                                |
| - | ------------------------------------------------------------------------------- | ------------------------------- | ------------------------- | ----------------------------------------------------- |
| 1 | [Top Pages by Traffic → Content Replication](top-pages-replication)             | site-explorer/top-pages         | Mave Agent + Generate     | Content briefs replicating top page patterns          |
| 2 | [Content Explorer → Trending Topics](trending-content-briefs)                   | content-explorer/search         | Personas + Focus Groups   | Validated content concepts from trending topics       |
| 3 | [Domain Rating Comparison → Competitive Positioning](domain-rating-positioning) | site-explorer/metrics           | Mave Agent + Brand Voices | Competitive positioning messaging by authority gap    |
| 4 | [Keyword Ideas → Generate at Scale](keyword-generate-at-scale)                  | keywords-explorer/keyword-ideas | Brand Voices + Generate   | SEO-optimized titles, metas, and outlines per cluster |

***

## Rate Limits & Production Notes

| Ahrefs Endpoint                 | Min Units | Caching Strategy                              |
| ------------------------------- | --------- | --------------------------------------------- |
| site-explorer/top-pages         | 50 units  | Cache 24h — page rankings shift daily at most |
| content-explorer/search         | 50 units  | Cache 12h — social shares update frequently   |
| site-explorer/metrics           | 50 units  | Cache 48h — domain rating changes slowly      |
| keywords-explorer/keyword-ideas | 50 units  | Cache per seed for 7 days                     |

<Warning>
  Ahrefs enforces **60 requests/minute** and a minimum of **50 units per request**. All jobs above include `time.sleep(1)` / `setTimeout(1000)` delays. In production, implement a centralized rate limiter across all Ahrefs calls. On `429 Too Many Requests`, retry after the `Retry-After` header value with exponential backoff (cap at 60s).
</Warning>

<Tip>
  Ahrefs returns proper JSON — no custom parsing needed. However, large result sets may be paginated via `offset` and `limit` parameters. Always check the response for a `has_more` field and loop if building complete datasets.
</Tip>

| Concern                  | Recommendation                                                                                                                                    |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| API token security       | Store in a secrets manager. Never commit to version control. Rotate tokens quarterly.                                                             |
| Unit monitoring          | Check balance before batch runs at [Ahrefs → API Usage](https://app.ahrefs.com/api/usage). A full keyword ideas + metrics audit costs 200+ units. |
| Response caching         | Ahrefs data updates daily at most. Cache with 24-48h TTL to preserve units.                                                                       |
| Mavera credits           | Monitor at [Dashboard](https://app.mavera.io/settings/usage). Batch generation jobs consume credits per call.                                     |
| Pagination               | For large datasets (1000+ keywords), use `offset` parameter in a loop. Add 1s delay between pages.                                                |
| OpenAI SDK compatibility | Mavera supports the OpenAI SDK with `base_url` pointed to `https://app.mavera.io/api/v1` and `model: "mave"`.                                     |

## What's Next

<CardGroup cols={2}>
  <Card title="All Integrations" icon="plug" href="/integrations">
    50+ API integrations with full code
  </Card>

  <Card title="Ahrefs API Docs" icon="magnifying-glass" href="https://docs.ahrefs.com/reference">
    Official Ahrefs API v3 reference
  </Card>

  <Card title="Mave Agent" icon="brain" href="/api-reference/mave">
    Full reference for POST /api/v1/mave/chat
  </Card>

  <Card title="Focus Groups API" icon="comments" href="/api-reference/focus-groups">
    Full reference for POST /api/v1/focus-groups
  </Card>

  <Card title="Generate API" icon="wand-magic-sparkles" href="/api-reference/generations">
    Full reference for POST /api/v1/generations
  </Card>

  <Card title="Brand Voices API" icon="bullhorn" href="/api-reference/brand-voices">
    Full reference for POST /api/v1/brand-voices
  </Card>
</CardGroup>