| name | sales-ahrefs |
| description | Ahrefs (ahrefs.com) platform help — industry-leading SEO toolset: Site Explorer (backlinks, organic keywords, Domain Rating), Keywords Explorer, Rank Tracker, Site Audit, Content Explorer, and Brand Radar AI-visibility. REST API v3 (api.ahrefs.com/v3, Bearer key, metered API units; v2 discontinued 2025-11-01) plus an official MCP server (Claude/ChatGPT/Cursor, Lite+). Use when building an Ahrefs API integration, your API units or monthly credits keep running out, setting up the Ahrefs MCP server with Claude, migrating off the dead v2 API to v3, getting throttled or locked by the 'suspicious activity' system within your limits, pulling backlinks/keywords/DR into a warehouse or report, deciding if you need the paid API subscription vs Enterprise, or choosing Starter vs Lite vs Standard vs Advanced. Do NOT use for SEO strategy or tool selection across vendors (use /sales-seo), AI-search-visibility tracking strategy across tools (use /sales-ai-visibility), or content optimization strategy (use /sales-seo). |
| argument-hint | [describe what you need help with in Ahrefs] |
| license | MIT |
| version | 1.0.0 |
| tags | ["sales","seo","content","platform"] |
| github | https://github.com/ahrefs |
Ahrefs Platform Help
Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated platform knowledge.
-
What are you trying to do?
- A) Build an API integration — pull backlinks, organic keywords, Domain Rating, rank data
- B) Set up the MCP server so Claude/ChatGPT can query your Ahrefs account by prompt
- C) Fix API units / monthly credits running out, overage fees, or "suspicious activity" throttling
- D) Migrate a dead v2 integration to v3
- E) Pick/understand a plan — Starter vs Lite vs Standard vs Advanced vs Enterprise; the credit + API-unit model
- F) Use a specific tool — Site Explorer, Keywords Explorer, Rank Tracker, Site Audit, Content Explorer, Brand Radar
-
REST or MCP? Scheduled pipelines/exports → REST API (tight select). Ad-hoc agent questions → the MCP server. Both spend the same API units.
Skip-ahead rule: if the user's prompt already provides enough context, skip to Step 2.
Step 2 — Route or answer directly
| If the question is about... | Route to... |
|---|
| SEO strategy, tool selection, or content optimization across vendors | /sales-seo {question} |
| AI-search-visibility (Brand Radar–style) tracking strategy across tools | /sales-ai-visibility {question} |
| Connecting Ahrefs data to other tools generically (iPaaS/warehouse) | /sales-integration {question} |
When routing, give the exact command, e.g. "This is an SEO-tool-selection question — run: /sales-seo Ahrefs vs Semrush for a small content team on a budget".
Step 3 — Ahrefs platform reference
Read references/platform-guide.md for the full reference — the module map (what's API vs MCP vs UI-only), the pricing model (the credit system on lower tiers, API-units allocation vs the paid API subscription/Enterprise for heavy use, $199/$99 add-ons, no free trial), the data model with JSON shapes, and quick-start recipes (pull competitor keywords unit-aware; wire the MCP into Claude; bulk-score domains with batch-analysis).
Read references/ahrefs-api-reference.md for the integration surface — base https://api.ahrefs.com/v3, Bearer auth (keys from Account → API keys, owners/admins, 1-yr expiry), the API-units cost model (min 50 units, scales with rows × fields, free endpoints), the endpoint groups (Site Explorer, Keywords Explorer, Rank Tracker, Site Audit, Batch Analysis, limits-and-usage), and the official MCP server setup.
Answer using only the relevant section. Don't dump the full reference.
Step 4 — Actionable guidance
Focus on the user's specific situation:
- Budget units like money. Every data call costs ≥50 units, scaling with rows × fields. Always pass
select (only needed fields), cap limit, prefer batch-analysis for many targets, cache,
and poll /subscription-info/limits-and-usage. This single discipline prevents most "ran out" pain.
- v3 only. v2 was fully shut off 2025-11-01 — any v2 tutorial/endpoint is dead. New keys + v3 paths.
- Use the MCP for agents, REST for pipelines. The official MCP (Lite+) lets Claude/ChatGPT pull data by
prompt; it draws on the same unit budget, so keep agent queries specific.
- Pace automated calls. Ahrefs' anti-abuse "suspicious activity" system throttles bursty access even
within plan limits — add jitter/backoff, don't hammer in parallel.
- Know the real cost. Lower tiers meter credits (1 per report); heavy API use needs a paid API
subscription (~$500–$10k/mo) or Enterprise; Brand Radar/AI Content Helper/Report Builder are paid add-ons.
- It's read-only. No write API, no event webhooks — pull data out, push it into your own systems.
If you discover a gotcha, workaround, or tip not covered in references/learnings.md, append it there.
Gotchas
Best-effort from research (2026-06) — review these, especially pricing/credits and the unit model, which change often.
- API units run out fast if you don't
select. Min 50/request and it scales with rows × fields. Request only the fields and rows you need; use batch-analysis and cache.
- API v2 is dead (since 2025-11-01). Build only on v3 with a fresh key; old v2 integrations have no data access.
- "Suspicious activity" lockouts hit legit users. Aggressive anti-abuse throttling can restrict you even inside plan limits — pace and back off automated calls.
- Credits ≠ API units. The in-app credit system (1 per report, e.g. 500/mo on Lite) is separate from the API-unit allocation. Both can be exhausted; both cause overage/limits.
- Heavy API use is expensive. The included unit allocation suits light use; production volume needs a paid API subscription ($500–$10k/mo) or Enterprise.
- No free trial; Starter is the cheap eval path. Don't expect a trial — Starter ($29) is the lowest-cost way to evaluate.
- Add-ons stack. Brand Radar ($199), AI Content Helper ($99), Report Builder ($99) are billed on top of the base plan.
- No affiliate program and no webhooks. Don't look for either — Ahrefs is a read-only research tool that deliberately runs no affiliate program.
Related skills
/sales-seo — SEO strategy and tool selection across vendors (Ahrefs vs Semrush vs cheaper suites), content + technical SEO
/sales-ai-visibility — AI-search-visibility tracking strategy across tools (Brand Radar is Ahrefs's add-on for this)
/sales-semrush — Semrush platform help (the closest all-in-one competitor)
/sales-integration — Connecting Ahrefs data to a warehouse/other tools (read-only pulls, no webhooks)
/sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do -a claude-code
Examples
Example 1: Pull a competitor's top keywords without blowing my units (developer/automation)
User says: "I want to export competitor.com's top 100 organic keywords from Ahrefs via the API."
Skill does: Walks Recipe 1 — GET /api/v3/site-explorer/organic-keywords?target=competitor.com&country=us&limit=100&select=keyword,volume,position,traffic with Authorization: Bearer. Stresses the unit math (min 50/request, scales with rows × fields), so a tight select + limit is essential, and to check /subscription-info/limits-and-usage first. Notes v3 only (v2 is dead) and keys come from Account → API keys (owners/admins).
Result: A unit-efficient keyword export.
Example 2: Let Claude query Ahrefs directly
User says: "Can I connect Ahrefs to Claude so I can just ask for backlink data?"
Skill does: Points to the official Ahrefs MCP server (Recipe 2), available on Lite+: claude mcp add --transport http ahrefs "https://mcp.ahrefs.com" --header "Authorization: Bearer $KEY" (verify the hosted URL in the MCP docs). Warns that MCP queries spend the same API units as REST, so keep prompts specific. Frames MCP as best for ad-hoc exploration vs REST for scheduled pipelines.
Result: Claude pulls Ahrefs SEO data by prompt, unit-aware.
Example 3: My Ahrefs bill/credits keep blowing up
User says: "I'm constantly hitting credit limits and overage fees on Ahrefs — is it just overpriced, or am I doing it wrong?"
Skill does: Separates the two meters — in-app credits (1 per report, 500/mo on Lite) vs API units — and gives concrete savings (use select/limit, batch-analysis, cache, monitor usage; upgrade tier or buy the API subscription only if genuinely needed). For the broader "is Ahrefs worth it vs Semrush/cheaper tools" decision, routes: "run: /sales-seo Ahrefs credit limits — is a cheaper SEO suite enough for me."
Result: User cuts usage waste and gets a path to the tool-selection decision.
Troubleshooting
My API calls fail or return "out of units"
Symptom: Requests error with a limits/units message, or stop returning data mid-month.
Cause: You've exhausted the monthly API-unit allocation — min 50 units/request scaling with rows × fields — or you're on a plan whose allocation suits only light use.
Solution: Add select to fetch only needed fields, lower limit, switch many single calls to batch-analysis, cache results, and watch /subscription-info/limits-and-usage. For sustained volume, move to a paid API subscription or Enterprise. Confirm you're on v3 (v2 was shut off 2025-11-01).
I keep getting throttled/locked even though I'm within my plan
Symptom: Restrictions or "suspicious activity" blocks despite staying within limits.
Cause: Ahrefs' anti-abuse system flags bursty/automated access patterns, sometimes catching legitimate API or heavy UI usage.
Solution: Pace requests (add delay + jitter), avoid heavy parallelism, back off on 429, and spread large jobs over time. If a legitimate workflow is blocked, contact Ahrefs support with your use case.
My old Ahrefs API integration stopped returning data
Symptom: A previously working integration now returns nothing/errors.
Cause: It was built on API v2, which was fully discontinued 2025-11-01 — v2 integrations no longer have data access.
Solution: Rebuild on API v3 (base https://api.ahrefs.com/v3, Bearer key from Account → API keys), update endpoint paths to the v3 groups, and adopt the API-units discipline (select, limit, batch). For AI agents, consider the MCP server instead.