---
name: ahrefs-api
description: Query the GroupBuySEO Ahrefs API gateway (wire-compatible with Ahrefs API v3) for backlinks, referring domains, organic keywords, domain rating, keyword research, SERP overview, rank tracking and site audit data. Use when the user asks for Ahrefs metrics, backlink profiles, keyword volume/difficulty, competitor SEO data, or wants to script against api.ahrefs.com without paying Ahrefs directly.
metadata:
  vendor: GroupBuySEO
  homepage: https://my.groupbuyseo.org/dashboard/api/products
  api_base_url: https://ahrefs-api.groupbuyseo.org/v3
---

# Ahrefs API (GroupBuySEO gateway)

Wire-compatible drop-in for **Ahrefs API v3** — same paths, same params, only
the host changes. Base URL: `https://ahrefs-api.groupbuyseo.org/v3`.

Auth: `Authorization: Bearer $AHREFS_API_KEY`. Read the key from the
environment; never hardcode it. Key lives at
<https://my.groupbuyseo.org/dashboard/api/keys>.

## Use the script, not raw curl

`scripts/ahrefs.mjs` handles auth, retries `429`/`502` with backoff, enforces
the 3-concurrent-request cap, and prints compact output. Prefer it over piping
large JSON into your context.

```bash
# Discover endpoints and their fields without loading any reference file
node scripts/ahrefs.mjs list
node scripts/ahrefs.mjs fields site-explorer/refdomains

# Query. --table prints aligned rows; --json only if you must post-process.
node scripts/ahrefs.mjs get site-explorer/domain-rating --target example.com
node scripts/ahrefs.mjs get site-explorer/refdomains \
  --target example.com --limit 20 \
  --select domain,domain_rating,links_to_target \
  --order-by domain_rating:desc --table

# Cost preview before spending units on a big pull
node scripts/ahrefs.mjs cost --select traffic,title,refdomains_source --rows 500

# Remaining balance (free call)
node scripts/ahrefs.mjs units
```

Add `--csv` for spreadsheet output, `--dry-run` to print the URL only.

## The five rules that cause most failures

1. **`select` is required** on most list endpoints, returns fields **in your
   order**, and an unknown field is a hard `400`. Check with
   `node scripts/ahrefs.mjs fields <endpoint>`.
2. **List responses are an object, not an array** — the single top-level key is
   the report name: `{ "refdomains": [ … ] }`.
3. **`date` (`YYYY-MM-DD`) is required** on most Site Explorer reports.
4. **Max 3 concurrent requests per key** — serialise, or get `429`.
5. **Cost is `max(50, per_row_cost × rows)`**, where `per_row_cost` sums the
   **unique** fields in `select` + `where` + `order_by`. Fields you filter or
   sort on are billed even when not returned. Always set `limit`.

## Cost tiers

`15` AI-citation fields (`chatgpt`, `gemini`, `perplexity`, …) · `10` traffic /
volume / difficulty / value fields · `5` refdomain-count fields · `1`
everything else. Free: Rank Tracker, Management, Public, Subscription Info,
Web Analytics, GSC, Social Media. Cached and failed requests cost 0.

Run `node scripts/ahrefs.mjs cost …` rather than estimating by hand.

## Errors

`400` bad/unknown `select` field — fix, don't retry · `401` bad key · `402`/`403`
out of units or missing scope — report, don't retry · `429` back off ·
`502` transient, retry with backoff.

Scope-gated areas (Site Audit projects, Web Analytics, GSC, Social Media,
shared Management) return empty or `400` when the account lacks that scope.
That is expected — don't retry or invent data.

## Reference files

Load only the one you need:

| File | Read it when |
|---|---|
| `reference/endpoints.md` | You need the full endpoint list with response keys and required params |
| `reference/fields.md` | You need valid `select` fields and their unit costs per endpoint |
| `reference/filters.md` | You need `where` / `order_by` JSON filter syntax |

Official upstream docs: <https://docs.ahrefs.com/>.
