Mattering Automations Ahrefs integration
Connect Ahrefs to Mattering Automations: Site Explorer backlinks and history, Keywords Explorer, SERP Overview, Batch Analysis, Rank Tracker, Site Audit and project management as workflow steps, on one API key. The Ahrefs API meters in units, so this guide starts with what each node spends.
The Mattering Automations Ahrefs integration puts Ahrefs API v3 on your automation canvas: Site Explorer overviews and seven history reports, backlinks, broken backlinks, referring domains, anchors and linked domains, organic and paid keyword reports, crawled pages, Keywords Explorer metrics and idea reports, SERP Overview, Batch Analysis for up to 100 targets in one request, five Rank Tracker reports, seven project and keyword-list management nodes, and two Site Audit nodes. Forty-six read and three act.
Read the money part first, because on this API it decides how you build. Ahrefs meters in API UNITS, and Ahrefs' documented formula is the greater of a 50 unit base cost and the per-row cost multiplied by the number of rows, where the per-row cost is the sum of the costs of each unique field appearing in the returned result or in the filter and sort parameters. Most fields cost 1 unit, some cost 5, some cost 10. Ahrefs' own worked example: a backlinks request selecting title and traffic, filtering on traffic and referring domains, sorting by traffic and returning 500 rows costs 6,000 units, because traffic alone is a 10 unit field. Ahrefs also states that units once consumed are non-refundable. The practical consequence is that the column list and the row limit are the two spending controls, and every metered node in the palette names its expensive columns.
Seventeen of the 49 nodes consume no units at all, by Ahrefs' own marking, and the setup below leans on them deliberately: Ahrefs: Get API Limits and Usage is free, all five Rank Tracker reports are free, all seven management nodes are free, and Ahrefs: List Site Audit Projects, Ahrefs: List Locations and Languages, Ahrefs: Get Domain Rating (Free Endpoint) and Ahrefs: List Crawler IP Ranges are free. So is the connection test. The credential is a single API v3 key sent as a bearer token, and this guide walks through creating it, connecting it, verifying without spending, and the full node reference.
Before you start
- An Ahrefs plan that includes API access. Ahrefs' current plan comparison table lists direct API access on all four plans, Lite through Enterprise, so it is not Enterprise-only, and Ahrefs' MCP documentation describes the same gate as a Lite plan or higher. There is no free API tier and no trial: Ahrefs Free is a limited user interface product rather than API access.
- An understanding of your plan's maximum rows per request, because it is applied silently. Ahrefs' pricing table gives it as 100 on Lite, 250 on Standard, 500 on Advanced and uncapped on Enterprise. A node asking for 1,000 rows on Lite returns 100 and does not error, so a workflow that needs certainty should compare the row count it received against the row count it asked for.
- A check on the two plan-gated things this integration touches. Ahrefs' plan comparison table lists Batch Analysis on three plans rather than four, so confirm Ahrefs: Batch Analysis against your own plan before building on it. And how far back the history reports can reach is a plan limit rather than a request limit, running from months on the entry plan to unlimited on Enterprise, so a windowed pull that quietly returns a shorter range than you asked for is usually the plan and not the node.
- Owner or admin access in the Ahrefs workspace, because only owners and admins can create an API key.
- A decision about the per-key monthly unit limit before you paste the key anywhere. It is set per key rather than per workspace, which makes it the one control that turns a runaway automation from a bill into an error.
- A Mattering workspace with access to the Automations app.
Create an Ahrefs API key
Mattering authenticates to Ahrefs with an API v3 key, sent as a bearer token on every request. There are no scopes to compose and no second field. Three properties of Ahrefs keys are worth knowing before you create one, because each of them has caused a working integration to stop working later: only owners and admins can create a key, a key expires one year after it is created, and a key is invalidated if the person who created it is removed from the workspace.
Connect Ahrefs to Mattering
Verify it works
Verify with the free nodes, because on this API there is no reason to pay for a smoke test. Open any automation canvas, drop Ahrefs: Get API Limits and Usage onto it and run a test step. It takes no parameters, costs nothing, and returns the plan, the monthly unit ceiling, the units spent so far and the key's expiry date. Those numbers are also the natural input to a spending guard at the front of any metered workflow.
Next prove a real data path without spending, using Ahrefs' own free test queries. Drop Ahrefs: Get Domain Rating onto the canvas and set the target to ahrefs.com, which Ahrefs documents as one of three free targets alongside yep.com and firehose.com. Site Explorer requests against those targets are free. The same carve-out covers Keywords Explorer and SERP Overview when the only keyword is ahrefs, yep or firehose, so Ahrefs: Get Keyword Metrics with the single keyword ahrefs is the free way to prove that half. Two conditions apply: the row limit is capped at 100 on a free request, and mixing any other keyword into the list, or passing a keyword list id, makes the whole request billable.
Finally check the free half against your own data. Run Ahrefs: List Projects, which is free and returns the projects in your workspace, then Ahrefs: Rank Tracker Overview against one of them, which is also free. If both return rows, the key, the plan and the workspace are all correct, and you have not spent a unit reaching that conclusion. Only then point a metered node at a real domain, starting with a small explicit limit and a short column list.
Node reference
49 nodes, generated from the connector itself so this reference always matches what ships.
Read and query nodes 46
Ahrefs: Batch Analysis
ahrefs_batch_analysis
COSTS API UNITS, and this node EXISTS TO SAVE THEM: up to 100 domains or URLs scored in ONE request, which pays the 50-unit floor once instead of a hundred times. Whenever a workflow would loop Ahrefs: Get Domain Rating or Ahrefs: Get Traffic and Keyword Metrics over a list, use this instead. Returns DR, UR, Ahrefs Rank, backlinks, referring domains and organic and paid traffic per target. org_traffic, org_cost, paid_traffic and paid_cost are 10 units each, the refdomains columns are 5, and org_traffic_top_by_country is 10 units PER COUNTRY returned. Monetary values are USD cents. Plan note: the number of targets is also bounded by the plan's Batch Analysis limit (200 on Standard, 500 on Advanced, 1,000 on Enterprise per report in the app), and Batch Analysis is not offered on Lite.
Ahrefs: Get API Limits and Usage
ahrefs_get_limits_and_usage
FREE - consumes no API units. How many API units this key and this workspace have spent this billing month, what the ceiling is, when it resets, and when the key itself expires. On a metered API this is the node to put in front of an expensive workflow: read data.limits_and_usage.units_usage_workspace against units_limit_workspace and branch rather than discovering the ceiling by hitting it. It is also the cheapest possible check that a credential works, since it needs no parameters and costs nothing.
Ahrefs: Get Backlinks Stats
ahrefs_get_backlinks_stats
COSTS API UNITS: one row of four fields, two of which are 5-unit columns, so this lands on the 50-unit minimum. Total live and all-time backlinks and referring domains for a target on a date. These are SNAPSHOT COUNTS, not activity in a period: data.metrics.live is how many links exist now, not how many were gained. Do not sum them across dates - for a series use Ahrefs: Get Referring Domains History.
Ahrefs: Get Domain Rating
ahrefs_get_domain_rating
COSTS 50 API UNITS per call - the flat minimum, because the endpoint returns one row of two fields and cannot be trimmed with select. Domain Rating and Ahrefs Rank for a target on a given date. If you only need TODAY'S DR, use Ahrefs: Get Domain Rating (Free Endpoint) instead and pay nothing; this node earns its cost only when you need a historical date or Ahrefs Rank. Both numbers are point-in-time scores on a relative scale - never add them up and never average them across sites or dates.
Ahrefs: Get Domain Rating (Free Endpoint)
ahrefs_get_domain_rating_free
FREE - consumes no API units, and works on a free Ahrefs account. Domain Rating for any domain, and nothing else. Use this instead of Ahrefs: Get Domain Rating whenever DR alone is what you need: that node costs the 50-unit minimum per call, this one costs nothing. It does still need an API key (Ahrefs made the key mandatory on 2026-08-10) and it cannot be dated - it always returns today's value. Using this data publicly requires the attribution Ahrefs states in data.license.
Ahrefs: Get Domain Rating History
ahrefs_get_domain_rating_history
COSTS API UNITS, priced per row: two 1-unit columns, so a monthly two-year pull is 24 rows at 2 units and lands on the 50-unit minimum, while the same range daily is 730 rows at 2 units and costs 1,460. Domain Rating over time, one row per bucket. DR IS A POINT-IN-TIME SCORE on a logarithmic scale relative to every other site in the index - it cannot be summed, and an average of DR values is not a meaningful number, so nothing here is aggregatable.
Ahrefs: Get Keyword Metrics
ahrefs_keywords_overview
COSTS API UNITS, and this is the node where a naive loop hurts most: the 50-unit floor is per REQUEST, so scoring 100 keywords one at a time costs 5,000 units minimum while one call with all 100 costs the same floor plus the row cost. ALWAYS PASS THE WHOLE LIST. Volume, difficulty, CPC, clicks, traffic potential, parent topic and search intent for a set of keywords. volume, difficulty, global_volume, traffic_potential and intents are 10 units EACH. cpc is in USD cents. FREE TEST: free when the only keywords are ahrefs, yep or firehose.
Ahrefs: Get Keyword Volume By Country
ahrefs_get_keyword_volume_by_country
COSTS API UNITS: one row per country with two 1-unit columns, so this normally lands on the 50-unit minimum. Where in the world a keyword is searched, ranked by volume - the market-selection report. Takes one keyword only. FREE TEST: free for the keywords ahrefs, yep or firehose.
Ahrefs: Get Keyword Volume History
ahrefs_get_keyword_volume_history
COSTS API UNITS: one keyword, one row per month, so a five-year pull is 60 rows and lands near the 50-unit minimum. But it takes ONE keyword only - checking seasonality across twenty keywords is twenty requests and twenty 50-unit floors, so batch that decision consciously. Monthly search volume for a keyword over time, which is how you tell a seasonal term from a dying one. Unlike every other history endpoint here, the grain is fixed monthly and the volumes ARE additive: summing twelve months gives the year's searches. FREE TEST: free for the keywords ahrefs, yep or firehose.
Ahrefs: Get Metrics By Country
ahrefs_get_metrics_by_country
COSTS API UNITS, and this one can get expensive: one row per country the target has any presence in, which is often dozens, multiplied by a per-row cost that the four traffic and cost columns push to 40+ units each. Trim Columns hard. Same metrics as Ahrefs: Get Traffic and Keyword Metrics, split by country, on one date. Monetary values are USD cents.
Ahrefs: Get Outlinks Stats
ahrefs_get_outlinks_stats
COSTS API UNITS: one row of four 1-unit fields, so the 50-unit minimum applies. How many external links and unique linked domains a target points OUT to, with dofollow counts. Ahrefs marks this endpoint BETA and warns its numbers may not match the Ahrefs UI exactly. Snapshot counts with no date parameter - there is no way to ask for a past value.
Ahrefs: Get Ranking Keywords History
ahrefs_get_keywords_history
COSTS API UNITS, priced per row; all columns here are 1 unit, so the bill is driven purely by how many buckets Grouping produces. How many keywords the target ranks for in each position band over time (top 3, 4-10, 11-20, 21-50, 51+). This is the report that shows rankings improving rather than just traffic moving. Each row is a standing at that point, so take the last row for a window and never sum the bands across dates.
Ahrefs: Get Ranking Pages History
ahrefs_get_pages_history
COSTS API UNITS, priced per row (two 1-unit columns; Grouping sets the row count). How many of the target's pages rank in the top 100 - or top 10, via Positions - over time. Each row is the count AT that point, a standing rather than an event, so the window's value is the last row.
Ahrefs: Get Referring Domains History
ahrefs_get_refdomains_history
COSTS API UNITS, priced per row, and note the column: refdomains is a 5-UNIT field, so a daily two-year pull is 730 rows at 6 units each, about 4,400 units. Monthly is 24 rows and hits the 50-unit floor. The count of unique referring domains over time - this is the link-growth chart. Each row is a CUMULATIVE SNAPSHOT of how many domains linked at that moment, not how many were gained in that bucket, so the window's figure is the last row and summing the rows is meaningless.
Ahrefs: Get SERP Overview
ahrefs_get_serp_overview
COSTS API UNITS: up to 100 rows for one keyword, and traffic, value and top_keyword_volume are 10 units each while refdomains is 5. Set Top positions to 10 rather than pulling the whole hundred. Who currently ranks for a keyword, with each result's DR, UR, backlinks and estimated traffic - the can-I-rank-here report. Takes ONE keyword: a loop over keywords pays the 50-unit floor every time, so scope those runs. value is in USD cents. FREE TEST: free for the keywords ahrefs, yep or firehose.
Ahrefs: Get Total Search Volume History
ahrefs_get_total_search_volume_history
COSTS API UNITS, and the metric column is a 10-UNIT field: a daily two-year pull is 730 rows at 11 units, roughly 8,000 units. Monthly is 24 rows and hits the 50-unit floor. The combined monthly search volume of every keyword the target ranks for in the top 10 (or top 100), over time - the addressable-demand chart. Each row is the total AS OF that point, so take the last row for a window rather than summing.
Ahrefs: Get Traffic Metrics History
ahrefs_get_metrics_history
COSTS API UNITS, priced per ROW, and the row count is set by Grouping: two years monthly is 24 rows, two years daily is 730. All four metric columns are 10-unit columns, so a daily two-year pull with everything selected is in the tens of thousands of units. Organic and paid traffic and their estimated values over time, one row per bucket, each carrying its own date. Monetary values are USD cents. THESE ARE GAUGES: each row is the estimated CURRENT monthly figure at that point, so the window's value is the last row, never the sum of the rows.
Ahrefs: Get Traffic and Keyword Metrics
ahrefs_get_metrics
COSTS API UNITS: one row, but four of its eight fields are 10-unit columns and the endpoint has no select, so the per-row cost is fixed and high - it still lands on the 50-unit minimum because it is a single row. The headline Site Explorer numbers for one target on one date: organic keywords and traffic, traffic value, paid keywords, paid traffic and paid cost. All monetary values are USD CENTS - divide by 100. Estimates of the current monthly figures on that date, not measurements of that day.
Ahrefs: Get URL Rating History
ahrefs_get_url_rating_history
COSTS API UNITS, priced per row (two 1-unit columns; Grouping sets the row count). URL Rating for a single page over time. Point this at a URL rather than a domain - on a bare domain it reports the homepage. UR IS A POINT-IN-TIME SCORE on a logarithmic scale and must never be summed or averaged, so this series is chartable but not aggregatable.
Ahrefs: List Anchor Texts
ahrefs_list_anchors
COSTS API UNITS, priced per row against the default limit of 1,000, though anchor reports are usually short. The anchor texts pointing at a target, with how many links and pages use each. This is the over-optimisation check: a commercial keyword dominating the anchor profile is the classic penalty signal. top_domain_rating is the single highest DR among the linking domains, a maximum rather than a total.
Ahrefs: List Backlinks
ahrefs_list_backlinks
COSTS API UNITS, and this is the single most expensive node in the connector if configured carelessly: cost is per-row cost times rows, the default limit is 1,000, and traffic and traffic_domain are 10-unit columns. Selecting traffic on a 1,000-row pull costs over 10,000 units by itself. Every backlink pointing at a target, with anchor text, follow status, first-seen date and the strength of the linking page. Set a small Max rows and sort by what you care about - there is no pagination, so a small sorted request IS the top-N query.
Ahrefs: List Best Pages By Backlinks
ahrefs_list_pages_by_backlinks
COSTS API UNITS, priced per row; only refdomains_target is above 1 unit here (5), so this is one of the cheaper link reports. Which of a target's own pages have attracted the most links, with the highest DR among their referrers. The internal-linking opportunity report: these pages hold the authority you can pass on. Formerly /site-explorer/best-by-external-links.
Ahrefs: List Broken Backlinks
ahrefs_list_broken_backlinks
COSTS API UNITS, priced per row against the default limit of 1,000 - the same arithmetic as Ahrefs: List Backlinks. Backlinks pointing at pages of yours that no longer resolve, with the target page's HTTP code. This is the link-reclamation report: every row is equity you already earned and are now throwing away on a 404. Note there is no history parameter here, unlike the main backlinks report.
Ahrefs: List Crawled Pages
ahrefs_list_crawled_pages
COSTS API UNITS, priced per row against the default limit of 1,000 - but every column here costs 1 unit, so a full 1,000 rows with all seven columns is about 7,000 units. Every URL of a target that AhrefsBot has crawled, with its HTTP status, title, URL Rating and crawl dates. Filter on http_code to find broken or redirecting pages without running a Site Audit.
Ahrefs: List Crawler IP Ranges
ahrefs_list_crawler_ip_ranges
FREE - consumes no API units and needs no API key at all. The IPv4 CIDR ranges AhrefsBot crawls from. This is the node for verifying that a hit in your access logs claiming to be AhrefsBot really is: user agents are trivially forged, IP ranges are not. Returns data.prefixes[].ipv4Prefix.
Ahrefs: List Keyword List Keywords
ahrefs_list_keyword_list_keywords
FREE - consumes no API units. The keywords saved in a Keywords Explorer list. Reading a list here is free; feeding its id into a Keywords Explorer node as Keyword list id is NOT, and makes that request billable even for the free test keywords - so pull the keywords with this node and pass them as a comma-separated Keywords value when you want the free path.
Ahrefs: List Linked Domains
ahrefs_list_linked_domains
COSTS API UNITS, priced per row against the default limit of 1,000. The domains a target links OUT to, with how many links and pages point at each. The outbound mirror of Ahrefs: List Referring Domains - useful for auditing who a site is endorsing, and for spotting sold links on someone else's.
Ahrefs: List Locations and Languages
ahrefs_list_locations
FREE - consumes no API units. The location ids and language codes available for one country, which are what Ahrefs: Add Project Keywords needs to place a tracked keyword in a city or a language. Note the shape: data.location.locations and data.location.languages are arrays of two-element PAIRS ([id, name] and [code, name]), not objects, which is why no picker reads from this node.
Ahrefs: List Matching Terms
ahrefs_list_matching_terms
COSTS API UNITS, priced per row, and keyword-idea reports return a LOT of rows: the default limit is 1,000 and the documented maximum is 150,000. With volume and difficulty selected that is 20 units a row. Set Max rows deliberately. Keyword ideas containing your seed terms - the bread-and-butter keyword-research report. Set Terms to questions for question-shaped ideas, and Match mode to phrase to require the words in order. FREE TEST: free when the only seeds are ahrefs, yep or firehose.
Ahrefs: List Organic Competitors
ahrefs_list_organic_competitors
COSTS API UNITS: traffic and value are 10-unit columns, though competitor lists are naturally short so a sensible Max rows keeps this cheap. The sites competing with a target for the same keywords, ranked by keyword overlap. Country is REQUIRED here, unlike most Site Explorer reports. value is in USD cents. share is each competitor's proportion of the shared keyword set.
Ahrefs: List Organic Keywords
ahrefs_list_organic_keywords
COSTS API UNITS, and the expensive columns here are the ones everyone wants: volume, keyword_difficulty and sum_traffic are 10 units EACH, so all three on a 1,000-row pull is 30,000+ units in one call. Every keyword a target ranks for, with its best position and the URL that holds it. Set a small Max rows and sort - there is no pagination. Setting a Comparison date turns on the _prev and _diff columns, which describe the comparison date rather than this row's date.
Ahrefs: List Paid Pages
ahrefs_list_paid_pages
COSTS API UNITS: sum_traffic, value and top_keyword_volume are 10 units each and referring_domains is 5. The landing pages a target runs paid search ads to, with how many ads and keywords point at each. This is the competitor-ad-spend report - what someone is willing to pay for tells you which pages make them money. value is in USD cents.
Ahrefs: List Project Competitors
ahrefs_list_project_competitors
FREE - consumes no API units. The competitors configured on a Rank Tracker project, with the scope each is tracked at. These are the domains that appear in Ahrefs: Rank Tracker Competitors Metrics, so read this when a competitor report shows fewer rivals than expected - the answer is usually that nobody added them to the project.
Ahrefs: List Project Keywords
ahrefs_list_project_keywords
FREE - consumes no API units. Every keyword tracked in a Rank Tracker project, with the location and language each is tracked in and any tags on it. This is the node to read before adding keywords, so a workflow does not re-add what is already there, and it is what supplies the location ids and language codes the SERP node and the delete node need.
Ahrefs: List Projects
ahrefs_list_projects
FREE - consumes no API units. Every project in the workspace with its id, name, target URL, scope, owner, folder and tracked-keyword count. This is the lister behind the project picker on every Rank Tracker node, so it runs whenever someone opens one of those config panels - which is safe precisely because it is free. Note data.projects[].project_id comes back as a STRING even though the parameter that consumes it is documented as an integer.
Ahrefs: List Referring Domains
ahrefs_list_refdomains
COSTS API UNITS, priced per row against the default limit of 1,000. One row per DOMAIN linking to the target, with its Domain Rating, how many links it sends, and when the first one appeared. Usually the report you want instead of Ahrefs: List Backlinks - it is a fraction of the rows for the same question, and the row count is what you are billed on. domain_rating is a point-in-time score: sort and filter on it, never total it.
Ahrefs: List Related Terms
ahrefs_list_related_terms
COSTS API UNITS, priced per row, default limit 1,000 and a documented maximum of 150,000 - the same spend arithmetic as Ahrefs: List Matching Terms. Keyword ideas that do NOT contain your seed: what the pages ranking for it also rank for (also_rank_for) and what they also talk about (also_talk_about). This is the topical-coverage report - it finds the subtopics a competing page covers and yours does not. FREE TEST: free when the only seeds are ahrefs, yep or firehose.
Ahrefs: List Search Suggestions
ahrefs_list_search_suggestions
COSTS API UNITS, priced per row, default limit 1,000 and a documented maximum of 150,000. Autocomplete suggestions for your seed keywords - what the search box offers people as they type, which is the closest thing to raw unfiltered demand. FREE TEST: free when the only seeds are ahrefs, yep or firehose.
Ahrefs: List Site Audit Issues
ahrefs_list_site_audit_issues
COSTS A FLAT 50 API UNITS per request - not per row, so pulling the whole issue list costs the same as pulling one, and there is no select to trim. Every technical SEO issue found in a Site Audit crawl, with its category, severity and how many URLs it affects. Set a Comparison date and the added, new, removed, missing and change columns fill in, which turns this into a regression alarm: branch on data.issues[].new being above zero for an Error-importance issue.
Ahrefs: List Site Audit Projects
ahrefs_list_site_audit_projects
FREE - consumes no API units. Health score and crawl summary for each Site Audit project: how many URLs were crawled, how many have errors, warnings and notices, and when the last crawl finished. The health score is a proportion of clean URLs at a point in time, so track it as a line and never total it. This is also the lister behind the project picker on Ahrefs: List Site Audit Issues, and only projects with a finished crawl appear.
Ahrefs: List Top Pages
ahrefs_list_top_pages
COSTS API UNITS, with the most 10-unit columns of any node here: sum_traffic, value, top_keyword_volume and all SEVEN ai_responses_* columns are 10 units each, and referring_domains is 5. Selecting the AI citation set alone adds 70 units per row. A target's best-performing pages by organic traffic, with the keyword driving each. Since 2026-07-30 the ai_responses_* columns report how often each page is cited by ChatGPT, Gemini, Perplexity, Copilot, Grok and Google's AI surfaces - which is the AI-visibility report, at ten units a column.
Ahrefs: Rank Tracker Competitors Metrics
ahrefs_rank_tracker_competitors_stats
FREE - consumes no API units. One summary row per competitor in the project: how many tracked keywords they hold in each position band, their average position, share of voice, and how many SERP features they own (AI overviews, featured snippets, image packs, video previews and the rest). Note the response region is data['competitors-metrics'] with a HYPHEN, which does not match the path's competitors-stats. average_position is an average already - do not average it again across dates without weighting.
Ahrefs: Rank Tracker Competitors Overview
ahrefs_rank_tracker_competitors_overview
FREE - consumes no API units. One row per tracked keyword, carrying a competitors_list array with where EVERY tracked competitor sits on that keyword. This is the head-to-head view: read data.overviews is wrong here, the region is data.keywords, and the per-competitor detail is nested inside each row rather than being its own row.
Ahrefs: Rank Tracker Competitors Pages
ahrefs_rank_tracker_competitors_pages
FREE - consumes no API units. Which PAGES, yours and your competitors', win the project's tracked keywords, with share of voice and share of traffic value for each. Note the response region is data['competitors-pages'] with a HYPHEN, not an underscore. Share of voice is a percentage of the tracked keyword set - a ratio, so never sum it across rows or dates.
Ahrefs: Rank Tracker Overview
ahrefs_rank_tracker_overview
FREE - the whole Rank Tracker tool consumes no API units, so this is the node to schedule daily without watching the meter. Every tracked keyword in a project with its current position, the ranking URL, volume, difficulty and SERP features. Device is required and desktop and mobile are tracked separately. Set a Comparison date to populate the _prev and _diff columns (position_diff is the movement report). Rows are per keyword per location, not per keyword.
Ahrefs: Rank Tracker SERP Overview
ahrefs_rank_tracker_serp_overview
FREE - consumes no API units, which is the whole reason to prefer it over Ahrefs: Get SERP Overview when the keyword is already tracked in a project. The full SERP Ahrefs last captured for one tracked keyword, with each result's DR, UR, backlinks and estimated traffic. The keyword must already be in the project - this reads a stored snapshot rather than buying a new one. This endpoint takes no select: it returns its whole column set.
Action nodes 3
Ahrefs: Add Keyword List Keywords
ahrefs_add_keyword_list_keywords
FREE - consumes no API units. Adds keywords to an existing Keywords Explorer list, which is how a research workflow hands its findings back to a human: run Ahrefs: List Matching Terms, filter it, and write the survivors into a list someone opens in the app. The list must already exist - v3 has no create-list endpoint. Reversible by removing the keywords in the Ahrefs UI. Keyword-list count is a plan limit (50 on Lite, 100 on Standard, 200 on Advanced, 500 on Enterprise).
Ahrefs: Add Project Keywords
ahrefs_add_project_keywords
FREE - consumes no API units, but it does consume the project's TRACKED KEYWORD allowance, which is a plan limit (750 on Lite, 2,000 on Standard, 5,000 on Advanced). Adds keywords to a Rank Tracker project. Every keyword is added in every location given, so 10 keywords x 3 locations is 30 tracked keywords, not 10. Reversible with Ahrefs: Delete Project Keywords, though removing and re-adding restarts that keyword's position history.
Ahrefs: Delete Project Keywords
ahrefs_delete_project_keywords
FREE - consumes no API units. DESTRUCTIVE AND IRREVERSIBLE: removing a keyword from a Rank Tracker project stops tracking it and discards its stored position history for that project. Re-adding it starts a new history from that day; the old positions do not come back. Each entry identifies ONE tracked row, so a keyword tracked in three locations needs three entries or two of them survive. Read Ahrefs: List Project Keywords first to get the exact country, location_id and language of each row.
Using the integration
On the automation canvas
Ahrefs nodes chain with every other node in the palette. A weekly schedule can run Ahrefs: Get API Limits and Usage, branch on the units left, and only then call Ahrefs: List Backlinks with a deliberate column list. A daily schedule can run the whole Rank Tracker set into a Mattering database for nothing. Project fields are pickers rather than free text: Ahrefs: List Projects feeds the project selector on the Rank Tracker and management nodes, Ahrefs: List Site Audit Projects feeds the one on Ahrefs: List Site Audit Issues (deliberately a separate lister, because a project that has never been crawled returns nothing from Site Audit), and the tracked-keyword field on Ahrefs: Rank Tracker SERP Overview only offers keywords from the project you already chose. All three listers are free endpoints, which is what makes a picker that re-populates as you type safe on a metered connector.
From AI assistants over MCP
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter, the assistant built into the platform, can drive the same surface. Ahrefs also runs its own hosted MCP server, documented with a streamable HTTP endpoint and setup guides for Claude, ChatGPT and other clients, on a Lite plan or higher, and for interactive questions it is a fine tool. The distinction is drawn by Ahrefs itself rather than by us, and it is worth quoting: using the external MCP endpoint via custom scripts, bridges, or standalone HTTP or JSON-RPC clients is unsupported and not permitted, the external MCP server is not a general-purpose programmatic API, and for supported programmatic access to Ahrefs data, please use the Ahrefs public API. This integration is that supported path. It calls the public v3 API under your own workspace key, so scheduled runs, multi-step workflows and chaining with the rest of the fleet all sit on the surface Ahrefs designed for them, with the credential held once in the workspace rather than in each person's client config.
Controlling what a request costs
Three levers, in order of effect. The COLUMN LIST is the first, because the per-row cost is the sum of the costs of each unique field appearing in the result or in the filter and sort parameters: traffic and traffic domain are 10 unit fields, several referring-domain columns are 5 unit fields, and the ordinary link columns are 1 unit each. Selecting fewer columns genuinely costs less. The ROW LIMIT is the second, because the per-row cost is multiplied by the rows returned, subject to the 50 unit floor on any billable request. The THIRD is choosing a free node where one answers the question: Ahrefs: Get Backlinks Stats sizes a profile at flat cost before Ahrefs: List Backlinks enumerates it, and the entire Rank Tracker and management set costs nothing. Two special shapes to remember: Ahrefs: List Site Audit Issues is a flat 50 units per request rather than per row, and the historical volume column on Ahrefs: Get Keyword Metrics bills per historical month with a 50 unit minimum, so on that one column a wider window costs more even at a constant row count.
Reading the responses without surprises
Ahrefs does not wrap responses in an envelope. The body is a single-key object naming the report, and the key is not always predictable from the path, so three traps are worth knowing before you write a template. The key metrics is an OBJECT on Ahrefs: Get Traffic and Keyword Metrics but an ARRAY on Ahrefs: Get Traffic Metrics History, Ahrefs: Get Metrics By Country and Ahrefs: Get Total Search Volume History. Two Rank Tracker keys carry hyphens, so they cannot be read with a dotted path: Ahrefs: Rank Tracker Competitors Pages returns its rows under a hyphenated competitors-pages key. And Ahrefs: Rank Tracker Competitors Metrics returns them under competitors-metrics, which does not match its own path and is the one nobody guesses. Every node's sample output shows the real shape, so read it rather than inferring. One more, and it silently changes numbers rather than breaking them: every monetary value in the API, including traffic value and cost columns, is in USD CENTS, so divide by 100 before anything renders it as money.
There is no pagination, and that is deliberate
No list endpoint in this integration accepts an offset, a page number or a cursor. There is only a limit, plus your plan's maximum rows per request. Two consequences follow, and both are easy to get wrong. First, a different slice comes from changing the sort and the filter, not from asking for page two, so a small limit plus a sort IS the top-N query. Second, do not try to assemble a full report from several smaller calls: these endpoints are ranked and truncated, so the membership of the result depends on the limit, and stitching two half-sized pulls together gives you something that is not the same as one larger pull. If you need everything, ask for everything in one request, within the plan's row cap, and price it accordingly.
The history reports, and what not to do with them
Seven Site Explorer history nodes take a date window and a grouping of daily, weekly or monthly, and one Keywords Explorer node returns monthly volume history. The important property is that Ahrefs' history rows are GAUGES rather than flows: each row is Ahrefs' estimate of the state at that point in time, not a count of things that happened during the bucket. Summing them is wrong at every grain and absurd at a daily one. So the declared roll-up for a window on those nodes is the latest value, and Ahrefs: Get Domain Rating History and Ahrefs: Get URL Rating History declare that they cannot be rolled up at all, because a rating is a position on a relative logarithmic scale rather than a quantity: an average of ratings is not a rating. The single exception is Ahrefs: Get Keyword Volume History, whose volume is a count of searches that occurred in a month, so twelve months there genuinely do add up to a year.
The three nodes that write, and the one that destroys
Forty-six of the 49 nodes only read. Ahrefs: Add Project Keywords and Ahrefs: Add Keyword List Keywords write keywords into a Rank Tracker project or a keyword list, cost no units, and are reversible in the ordinary sense. Ahrefs: Delete Project Keywords is flagged destructive rather than merely reversible, and the reason is specific: removing a keyword from a project discards its position history, so re-adding it starts a fresh history from that day and the old positions do not come back. Its other sharp edge is partial deletion that looks complete, because each entry identifies ONE tracked row, so a keyword tracked in three locations needs three entries. Gate it behind a condition or an approval step, particularly if an AI agent can reach the palette. No node in this integration creates or deletes an Ahrefs project.
Troubleshooting
Test Connection passes but a data node returns an error
A node returned far fewer rows than the limit I set
A request spent many more units than expected
A request I expected to be free was billed
Requests start returning HTTP 429
A key that worked yesterday now fails authentication
A template reading a Rank Tracker response resolves to nothing
Traffic value or cost numbers look a hundred times too large
The location, language or keyword list picker will not populate
Related
The Ahrefs MCP
What connecting Ahrefs unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
Ahrefs is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.