Ahrefs

Ahrefs

Ahrefs spans six research surfaces. Pick the surface that matches the question before pulling data — competitor recon, rank monitoring, keyword discovery, AI-search visibility, technical crawls, and first-party traffic are different products with different ids.

First moves

1. Usage check — read subscription limits and current API unit consumption before large scans.
2. List projects — resolve the numeric project id when the user names a tracked site (Rank Tracker, Web Analytics, or management reads).
3. Site Explorer snapshot — domain-level metrics, organic keywords, backlinks, or top pages for any public target without a project id.
4. Rank Tracker overview — tracked-keyword positions for an existing project when the user asks "where do we rank today".
5. Keywords Explorer — ad-hoc keyword difficulty, volume, and SERP context for seeds not yet in a Rank Tracker list.
6. Brand Radar report — AI-search mentions, citations, and share-of-voice for a configured report id.
7. Site Audit health — crawl issues, affected pages, and link graph for a verified Site Audit project.
8. Web Analytics — first-party visit trends for a connected analytics project (not Site Explorer traffic estimates).

Pick the right surface

• Site Explorer — "What does Ahrefs know about this domain or URL on the public web?" Competitor research, link audits, traffic estimates, and one-off lookups. Pass any target domain or URL; no project setup required.
• Rank Tracker — "Where does my tracked project rank for my keyword list today vs yesterday?" Ongoing monitoring only — keywords must already live in a Rank Tracker project.
• Keywords Explorer — "Should we target this keyword?" Research volume, difficulty, parent topics, and SERP features for seeds the user has not added to Rank Tracker yet.
• Brand Radar — "How visible are we in AI answers?" Mentions, citations, and share-of-voice across ChatGPT, Perplexity, Google AI Overview, Gemini, and similar surfaces for tracked prompts.
• Site Audit — "What is broken on our site technically?" Crawl health, issue counts, internal links, and page-level flags after domain ownership is verified.
• Web Analytics — "What is happening on our site right now?" First-party visit and conversion data piped into Ahrefs — not the third-party traffic model Site Explorer shows.

Project and report ids

• Rank Tracker and Web Analytics share one numeric project_id. List projects and match the tracked URL — never guess the integer.
• Site Audit uses a separate project namespace; a Rank Tracker project_id will not work for audit reads. Most audit work requires verified domain ownership on that project.
• Brand Radar uses report_id (numeric, from the Brand Radar report URL). Brand Radar reads never accept a Rank Tracker project_id.
• Keyword lists use keyword_list_id — a standalone list surface distinct from project tracked keywords.

Operational order

1. When the user says "rankings" without context, ask whether they mean tracked project positions (Rank Tracker) or market research on a domain (Site Explorer / Keywords Explorer).
2. Resolve project_id or report_id from a list call before drilling into project-scoped reads.
3. For competitor domains, start with Site Explorer metrics and organic keywords; switch to Rank Tracker only when monitoring a saved keyword set.
4. Apply tight limit values on row-priced reads; widen only when the user needs exhaustive exports.

Rank Tracker maintenance

When adding competitors or tracked keywords, payloads are object arrays, not bare strings.

• Competitor items: { "url": "<domain or url>", "mode": "domain" | "subdomains" | "exact" | "prefix" }. Prefer subdomains for whole-brand tracking (www, app, m, etc.); domain excludes subdomains.
• Tracked-keyword items: locations as [{ "country": "us", "language": "en" }, ...] and keywords as [{ "keyword": "...", "tags": ["..."] }, ...] (tags optional).
• Standalone keyword-list updates accept a flat string array of keywords — different shape from project tracked-keyword writes.

Column-name traps (select)

Each report exposes its own column identifiers; the wrong name returns an error listing allowed columns. Repeated traps:

• Site Explorer organic keywords — best_position and best_position_url; position and bare url are invalid there.
• Rank Tracker overview — position and url for the tracked keyword's current rank.
• Organic competitors — keywords_common, not common_keywords.

Web Analytics date argument

Tabular and chart reads accept to and from_ (trailing underscore on from_). Pass from_ in tool arguments; upstream receives the plain from field name.

Date formats

• Site Explorer, Rank Tracker, Keywords Explorer, Brand Radar, Web Analytics — YYYY-MM-DD or ranges with the same format.
• Site Audit crawl slices — YYYY-MM-DDThh:mm:ss timestamps; omit the date to read the latest stored crawl.

API units

Most analytics reads consume API units against the monthly allowance; management lists and Rank Tracker writes are typically free. Row-priced surfaces (Site Explorer, Keywords Explorer, Brand Radar, Web Analytics) bill per row returned — keep limit low while exploring.