sales-skills/sales-ahrefs

Ahrefs Platform Help

Step 1 — Gather context

If references/learnings.md exists, read it first for accumulated platform knowledge.

1. 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

2. 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.

1. 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.
2. API v2 is dead (since 2025-11-01). Build only on v3 with a fresh key; old v2 integrations have no data access.
3. "Suspicious activity" lockouts hit legit users. Aggressive anti-abuse throttling can restrict you even inside plan limits — pace and back off automated calls.
4. 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.
5. Heavy API use is expensive. The included unit allocation suits light use; production volume needs a paid API subscription ($500–$10k/mo) or Enterprise.
6. No free trial; Starter is the cheap eval path. Don't expect a trial — Starter ($29) is the lowest-cost way to evaluate.
7. Add-ons stack. Brand Radar ($199), AI Content Helper ($99), Report Builder ($99) are billed on top of the base plan.
8. 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.