Ahrefs

Ahrefs

This connector calls the Ahrefs API v3 (https://api.ahrefs.com/v3) with the user's own API key: Site Explorer (Domain Rating, backlinks, referring domains, anchors, organic keywords, top pages, competitors, metrics and history), Keywords Explorer (overview, matching and related terms, volume history), SERP Overview and Batch Analysis. Every tool is a read.

Every request spends API units from the Ahrefs workspace. A request costs max(50, per_row_cost x rows): at least 50 units, otherwise the sum of the unit costs of every column in select, where and order_by (1 unit by default, 5 or 10 for metrics such as traffic, volume, difficulty and referring domains), times the rows returned. Each tool says what its default columns cost. limit defaults to 10 rows: raise it only when needed, and select only the columns the answer needs. Requests served from Ahrefs' cache are free. ahrefs_get_limits_and_usage is free and shows the units used and left.

Free test queries: Site Explorer requests on ahrefs.com, yep.com or firehose.com (or their URLs) and Keywords Explorer or SERP Overview requests for the keywords ahrefs, yep or firehose alone cost nothing (capped at 100 rows). Use them to try a tool.

Setup (about 3 minutes)

1. API access comes with eligible paid Ahrefs plans, each with a monthly API unit allowance (see https://ahrefs.com/pricing); other plans can only run the free test queries. Only workspace owners and admins can create keys.
2. Open Account settings, API keys (https://app.ahrefs.com/account/api-keys), create a key, and consider a monthly unit limit for it.
3. Paste it into AHREFS_API_KEY and install. It is stored encrypted and sent as Authorization: Bearer only to api.ahrefs.com.

Tools

• ahrefs_get_limits_and_usage: plan, units used and allowed, reset date (free).
• ahrefs_domain_rating: Domain Rating and Ahrefs Rank.
• ahrefs_backlinks_stats: live and all-time backlinks and referring domains.
• ahrefs_site_metrics: organic and paid keywords, traffic and traffic value.
• ahrefs_metrics_history: traffic and traffic value over time.
• ahrefs_domain_rating_history: Domain Rating over time.
• ahrefs_backlinks: backlinks.
• ahrefs_referring_domains: referring domains.
• ahrefs_anchors: anchor texts.
• ahrefs_organic_keywords: keywords a domain or URL ranks for.
• ahrefs_top_pages: pages with the most organic traffic.
• ahrefs_organic_competitors: organic competitors in a country.
• ahrefs_keywords_overview: volume, difficulty, CPC, traffic potential of given keywords.
• ahrefs_matching_terms: keyword ideas containing the seed words, or questions.
• ahrefs_related_terms: related keywords of the top-ranking pages.
• ahrefs_volume_history: monthly volume of one keyword.
• ahrefs_serp_overview: the recorded Google top results for a keyword.
• ahrefs_batch_analysis: up to 100 targets compared in one call (POST, read-only).

Parameters: date (YYYY-MM-DD) is required by most Site Explorer tools; use today's date for current data. country is a lower-case two-letter code. mode sets the scope of target: subdomains (default), domain, prefix or exact. order_by takes column:asc or column:desc. where takes Ahrefs' JSON filter, e.g. {"and":[{"field":"volume","is":["gte",100]},{"field":"keyword","is":["isubstring","shoes"]}]}. CPC and traffic value are in USD cents.

Common errors (Ahrefs answers ["Error", "<reason>"])

• 401 Unauthorized: the API key is wrong, expired or was deleted. Create a new one in Account settings, API keys.
• 403 Forbidden: the plan has no API access, the key or workspace has used its unit limit, or the request is outside the plan (for example more rows than the plan allows per request).
• 400: a parameter is invalid; the reason names it (for example an unknown column in select).
• 429: more than 60 requests a minute, or Ahrefs is throttling; wait and retry.

Out of scope here: Rank Tracker, Site Audit, Brand Radar, Web Analytics, GSC Insights, Social Media, Content Helper and the management endpoints (projects, keyword lists).