opensource/sim
3
0
Fork 0
mirror of https://github.com/simstudioai/sim.git synced 2026-09-24 15:45:35 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(ahrefs): validate integration, fix cents/column bugs, add 13 v3 endpoints (#5447)

Browse Source 
* feat(ahrefs): validate integration, fix cents/column bugs, add 13 v3 endpoints

Audited the existing Ahrefs integration against live API v3 docs and fixed
real bugs: broken_backlinks selected the wrong column (http_code_target
instead of http_code), and keyword_overview/metrics/metrics_history returned
CPC/cost fields in USD cents without converting to USD. Also fixed the
top-pages mode dropdown missing the "exact" option.

Added 13 new tools covering previously-unsupported Ahrefs v3 endpoints:
Rank Tracker (overview, SERP overview, competitors overview, competitors
stats), Batch Analysis, Site Audit page explorer, four history/trend
endpoints (domain rating, metrics, referring domains, keywords), Related
Terms, Anchors, and Paid Pages.

Note: the CPC/cost unit fix silently shifts existing organicCost/paidCost/cpc
values by 100x for any workflow already consuming them (the old values were
wrong, in cents instead of dollars).

* fix(ahrefs): convert remaining cents-to-USD fields, drop unneeded fallback key

Rank Tracker SERP Overview's value field, Competitors Stats' trafficValue,
and Competitors Overview's nested competitor value were all left in USD
cents while every other monetary field in the integration converts to USD
- fixed for consistency with the rest of the integration.

Also drops the unverified `data.results` fallback in Batch Analysis; the
Ahrefs v3 docs confirm the response key is always `targets`.

* docs(ahrefs): regenerate docs to reflect cents-to-USD conversion fix

The generated docs page was stale after the previous commit converted
rank_tracker_serp_overview.value, rank_tracker_competitors_stats.trafficValue,
and rank_tracker_competitors_overview's nested value from cents to USD -
regenerating picks up the corrected field descriptions.

* fix(ahrefs): revert incorrect broken_backlinks column, fix missed top_pages conversion, revert unverified competitor value conversions

Independent re-verification against live Ahrefs v3 docs surfaced two real
regressions from the earlier fix rounds and one missed conversion:

- broken_backlinks: the earlier fix changed the selected column from
  http_code_target to http_code, but the docs say http_code is the
  *referring page's* status and http_code_target is the *broken target
  page's* status - the tool needs the latter (matches its own output
  description). Reverted to http_code_target.
- top_pages: value field was never divided by 100 despite the docs stating
  it's in USD cents and the output already claiming USD - fixed.
- rank_tracker_competitors_stats.trafficValue and the nested competitor.value
  in rank_tracker_competitors_overview were converted from cents to USD last
  round on a "match every other monetary field" assumption, but the live docs
  do not document these two fields as cents (unlike every field that was
  correctly converted). Reverted to passthrough and dropped the "(USD)"
  claim from their descriptions until Ahrefs documents the unit.

Also added the missing "exact" mode option to top_pages' mode param
description, matching every sibling tool.

* fix(ahrefs): convert rank tracker competitor value/trafficValue to USD

Both bots independently flagged these two fields as inconsistent with
every other monetary field in the integration, all 7 of which are
explicitly documented as USD cents. Neither field has explicit unit
documentation (one is undocumented as cents, the other's schema isn't
statically retrievable at all), but given the unanimous pattern across
every other verified field and no contrary evidence, converting for
consistency is the better bet than leaving them as an outlier.

* style(ahrefs): drop non-TSDoc inline comments introduced in this PR

Repo convention disallows non-TSDoc comments; removed the three
explanatory // comments this PR added next to cents-to-USD conversions
(keyword_overview, paid_pages, related_terms) - pre-existing comments
elsewhere in the file are untouched, out of scope for this PR.

* fix(ahrefs): default optional country to us consistently across all tools

paid_pages, metrics_history, keywords_history, and batch_analysis were the
only 4 of the 11 tools with an optional country param that didn't fall back
to "us" when omitted, unlike domain_rating, metrics, keyword_overview,
organic_keywords, organic_competitors, top_pages, and related_terms - all
of which default client-side. Aligned all four to the same convention so
direct tool/agent calls without an explicit country get the same behavior
regardless of which operation is used.

* fix(ahrefs): split shared date subBlock id for datetime-format operations

site_audit_page_explorer and rank_tracker_serp_overview both reused the
generic 'date' subBlock id with YYYY-MM-DDThh:mm:ss semantics, while every
other operation using that same id expects YYYY-MM-DD. Switching operations
without clearing the field could carry a stale wrong-format value into the
new operation's request. Split into distinct ids (crawlDate, asOfDate)
mapped back to each tool's date param in tools.config.params.
This commit is contained in:
Waleed
2026-07-06 16:07:03 -07:00
committed by GitHub
parent be6f69365c
commit 918ba8a86a
22 changed files with 3475 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/content/docs/en/integrations/ahrefs.mdx
+373 -3
View File
@@ -18,8 +18,8 @@ With the Ahrefs integration in Sim, you can:
- **Analyze Domain Rating & Authority**: Instantly check the Domain Rating (DR) and Ahrefs Rank of any website to gauge its authority.
- **Fetch Backlinks**: Retrieve a list of backlinks pointing to a site or specific URL, with details like anchor text, referring page DR, and more.
- **Get Backlink Statistics**: Access metrics on backlink types (dofollow, nofollow, text, image, redirect, etc.) for a domain or URL.
- **Explore Organic Keywords** *(planned)*: View keywords a domain ranks for and their positions in Google search results.
- **Discover Top Pages** *(planned)*: Identify the highest-performing pages by organic traffic and links.
- **Explore Organic Keywords**: View keywords a domain ranks for and their positions in Google search results.
- **Discover Top Pages**: Identify the highest-performing pages by organic traffic and links.
These tools let your agents automate SEO research, monitor competitors, and generate reports—all as part of your workflow automations. To use the Ahrefs integration, you’ll need an Ahrefs Enterprise subscription with API access.
{/* MANUAL-CONTENT-END */}
@@ -244,7 +244,7 @@ Get the top pages of a target domain sorted by organic traffic. Returns page URL
| --------- | ---- | -------- | ----------- |
| `target` | string | Yes | The target domain to analyze. Example: "example.com" |
| `country` | string | No | Country code for traffic data. Example: "us", "gb", "de" \(default: "us"\) |
| `mode` | string | No | Analysis mode: domain \(entire domain\), prefix \(URL prefix\), subdomains \(include all subdomains, default\). Example: "domain" |
| `mode` | string | No | Analysis mode: domain \(entire domain\), prefix \(URL prefix\), subdomains \(include all subdomains, default\), exact \(exact URL match\). Example: "domain" |
| `date` | string | No | Date to report metrics on, in YYYY-MM-DD format \(defaults to today\) |
| `limit` | number | No | Maximum number of results to return. Example: 50 \(default: 1000\) |
| `apiKey` | string | Yes | Ahrefs API Key |
@@ -293,4 +293,374 @@ Get detailed metrics for a keyword including search volume, keyword difficulty,
| ↳ `branded` | boolean | Query references a specific brand |
| ↳ `local` | boolean | Query seeks local results |
### `ahrefs_paid_pages`
Get a target domain's pages that receive paid search traffic, sorted by estimated paid traffic. Returns page URLs with their paid traffic, keyword counts, and estimated spend.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `target` | string | Yes | The target domain or URL to analyze. Example: "example.com" |
| `country` | string | No | Country code for traffic data. Example: "us", "gb", "de" \(default: "us"\) |
| `mode` | string | No | Analysis mode: domain \(entire domain\), prefix \(URL prefix\), subdomains \(include all subdomains, default\), exact \(exact URL match\) |
| `date` | string | No | Date to report metrics on, in YYYY-MM-DD format \(defaults to today\) |
| `limit` | number | No | Maximum number of results to return. Example: 50 \(default: 1000\) |
| `apiKey` | string | Yes | Ahrefs API Key |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `paidPages` | array | List of pages receiving paid search traffic |
| ↳ `url` | string | The page URL |
| ↳ `traffic` | number | Estimated monthly paid search traffic |
| ↳ `keywords` | number | Number of paid keywords the page ranks for |
| ↳ `topKeyword` | string | The top keyword driving paid traffic to this page |
| ↳ `value` | number | Estimated monthly paid traffic cost in USD |
| ↳ `adsCount` | number | Number of unique ads shown for this page |
### `ahrefs_anchors`
Get the anchor text distribution for a target domain or URL's backlinks, showing how many links and referring domains use each anchor text.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `target` | string | Yes | The target domain or URL to analyze. Example: "example.com" or "https://example.com/page" |
| `mode` | string | No | Analysis mode: domain \(entire domain\), prefix \(URL prefix\), subdomains \(include all subdomains, default\), exact \(exact URL match\) |
| `history` | string | No | Historical scope: "live" \(currently live\), "all_time" \(default, includes lost backlinks\), or "since:YYYY-MM-DD" \(backlinks found since a date\) |
| `limit` | number | No | Maximum number of results to return. Example: 50 \(default: 1000\) |
| `apiKey` | string | Yes | Ahrefs API Key |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `anchors` | array | Anchor text distribution for the backlink profile |
| ↳ `anchor` | string | The anchor text |
| ↳ `backlinks` | number | Total backlinks using this anchor text |
| ↳ `dofollowBacklinks` | number | Number of dofollow backlinks using this anchor text |
| ↳ `referringDomains` | number | Number of unique referring domains using this anchor text |
| ↳ `firstSeen` | string | When a link with this anchor was first found |
| ↳ `lastSeen` | string | When a backlink with this anchor was last seen \(null if still live\) |
### `ahrefs_related_terms`
Get keyword ideas related to a seed keyword: terms the same top-ranking pages also rank for ("also rank for") or also discuss ("also talk about"), with volume, difficulty, and CPC.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `keyword` | string | Yes | The seed keyword to find related terms for |
| `country` | string | No | Country code for keyword data. Example: "us", "gb", "de" \(default: "us"\) |
| `terms` | string | No | Type of related keywords to return: "also_rank_for", "also_talk_about", or "all" \(default: "all"\) |
| `viewFor` | string | No | Whether to derive related terms from the top 10 or top 100 ranking pages \(default: "top_10"\) |
| `limit` | number | No | Maximum number of results to return. Example: 50 \(default: 1000\) |
| `apiKey` | string | Yes | Ahrefs API Key |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `relatedTerms` | array | Related keyword ideas for the seed keyword |
| ↳ `keyword` | string | The related keyword |
| ↳ `volume` | number | Average monthly search volume |
| ↳ `keywordDifficulty` | number | Keyword difficulty score \(0-100\) |
| ↳ `cpc` | number | Cost per click in USD |
| ↳ `parentTopic` | string | The parent topic for this keyword |
| ↳ `trafficPotential` | number | Estimated traffic potential if ranking #1 |
| ↳ `intents` | object | Search intent flags \(informational, navigational, commercial, transactional, branded, local\) |
| ↳ `serpFeatures` | array | SERP features present in the results |
### `ahrefs_domain_rating_history`
Get the historical Domain Rating (DR) trend for a target domain or URL over a date range, grouped daily, weekly, or monthly.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `target` | string | Yes | The target domain or URL to analyze. Example: "example.com" |
| `dateFrom` | string | Yes | Start date of the historical period, in YYYY-MM-DD format |
| `dateTo` | string | No | End date of the historical period, in YYYY-MM-DD format \(defaults to today\) |
| `historyGrouping` | string | No | Time interval for grouping data points: "daily", "weekly", or "monthly" \(default: "monthly"\) |
| `apiKey` | string | Yes | Ahrefs API Key |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `domainRatings` | array | Historical Domain Rating data points |
| ↳ `date` | string | The date of the measurement |
| ↳ `domainRating` | number | Domain Rating score \(0-100\) on this date |
### `ahrefs_metrics_history`
Get the historical organic and paid traffic trend for a target domain or URL over a date range: organic traffic/cost and paid traffic/cost at each point in time.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `target` | string | Yes | The target domain or URL to analyze. Example: "example.com" |
| `dateFrom` | string | Yes | Start date of the historical period, in YYYY-MM-DD format |
| `dateTo` | string | No | End date of the historical period, in YYYY-MM-DD format \(defaults to today\) |
| `volumeMode` | string | No | Search volume calculation: "monthly" or "average" \(default: "monthly"\) |
| `historyGrouping` | string | No | Time interval for grouping data points: "daily", "weekly", or "monthly" \(default: "monthly"\) |
| `country` | string | No | Country code for traffic data. Example: "us", "gb", "de" \(default: "us"\) |
| `mode` | string | No | Analysis mode: domain \(entire domain\), prefix \(URL prefix\), subdomains \(include all subdomains, default\), exact \(exact URL match\) |
| `apiKey` | string | Yes | Ahrefs API Key |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `metricsHistory` | array | Historical organic and paid traffic data points |
| ↳ `date` | string | Date of the metric entry |
| ↳ `organicTraffic` | number | Estimated monthly organic visits |
| ↳ `organicCost` | number | Estimated monthly cost to replicate organic traffic via ads \(USD\) |
| ↳ `paidTraffic` | number | Estimated monthly paid search visits |
| ↳ `paidCost` | number | Estimated monthly paid search spend \(USD\) |
### `ahrefs_refdomains_history`
Get the historical referring domains trend for a target domain or URL over a date range, grouped daily, weekly, or monthly.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `target` | string | Yes | The target domain or URL to analyze. Example: "example.com" |
| `dateFrom` | string | Yes | Start date of the historical period, in YYYY-MM-DD format |
| `dateTo` | string | No | End date of the historical period, in YYYY-MM-DD format \(defaults to today\) |
| `historyGrouping` | string | No | Time interval for grouping data points: "daily", "weekly", or "monthly" \(default: "monthly"\) |
| `mode` | string | No | Analysis mode: domain \(entire domain\), prefix \(URL prefix\), subdomains \(include all subdomains, default\), exact \(exact URL match\) |
| `apiKey` | string | Yes | Ahrefs API Key |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `referringDomainsHistory` | array | Historical referring domains count data points |
| ↳ `date` | string | The date of the data point |
| ↳ `referringDomains` | number | Total number of unique domains linking to the target on this date |
### `ahrefs_keywords_history`
Get the historical organic keyword ranking distribution for a target domain or URL over a date range: how many keywords rank in each position bucket at each point in time.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `target` | string | Yes | The target domain or URL to analyze. Example: "example.com" |
| `dateFrom` | string | Yes | Start date of the historical period, in YYYY-MM-DD format |
| `dateTo` | string | No | End date of the historical period, in YYYY-MM-DD format \(defaults to today\) |
| `historyGrouping` | string | No | Time interval for grouping data points: "daily", "weekly", or "monthly" \(default: "monthly"\) |
| `country` | string | No | Country code for search results. Example: "us", "gb", "de" \(default: "us"\) |
| `mode` | string | No | Analysis mode: domain \(entire domain\), prefix \(URL prefix\), subdomains \(include all subdomains, default\), exact \(exact URL match\) |
| `apiKey` | string | Yes | Ahrefs API Key |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `keywordsHistory` | array | Historical organic keyword ranking distribution |
| ↳ `date` | string | Date of the record |
| ↳ `top3` | number | Keywords ranking in top 3 organic results |
| ↳ `top4To10` | number | Keywords ranking in positions 4-10 |
| ↳ `top11To20` | number | Keywords ranking in positions 11-20 |
| ↳ `top21To50` | number | Keywords ranking in positions 21-50 |
| ↳ `top51Plus` | number | Keywords ranking in position 51 and beyond |
### `ahrefs_batch_analysis`
Get bulk SEO metrics (Domain Rating, backlinks, referring domains, organic traffic, and more) for multiple domains or URLs in a single request. Useful for comparing many competitors at once.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `targets` | string | Yes | Comma-separated list of domains or URLs to analyze. Example: "example.com,competitor.com" |
| `mode` | string | No | Analysis mode applied to every target: domain \(entire domain\), prefix \(URL prefix\), subdomains \(include all subdomains, default\), exact \(exact URL match\) |
| `protocol` | string | No | Protocol applied to every target: "both" \(default\), "http", or "https" |
| `country` | string | No | Country code for traffic data. Example: "us", "gb", "de" \(default: "us"\) |
| `volumeMode` | string | No | Search volume calculation: "monthly" or "average" \(default: "monthly"\) |
| `apiKey` | string | Yes | Ahrefs API Key |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `results` | array | Bulk metrics for each analyzed target, in submission order |
| ↳ `url` | string | The analyzed target URL or domain |
| ↳ `index` | number | Index of the target in the submitted list |
| ↳ `domainRating` | number | Domain Rating score \(0-100\) |
| ↳ `ahrefsRank` | number | Ahrefs Rank \(global ranking\) |
| ↳ `backlinks` | number | Total backlinks to the target |
| ↳ `referringDomains` | number | Unique domains linking to the target |
| ↳ `organicTraffic` | number | Estimated monthly organic traffic |
| ↳ `organicKeywords` | number | Number of organic keywords ranked \(top 100\) |
| ↳ `paidTraffic` | number | Estimated monthly paid search traffic |
| ↳ `error` | string | Error message if this target could not be analyzed |
### `ahrefs_site_audit_page_explorer`
Get crawled pages from an Ahrefs Site Audit project with health and SEO metrics: HTTP status, title, link counts, backlinks, indexability, and traffic. Optionally filter to pages affected by a specific issue.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `projectId` | number | Yes | The Site Audit project ID \(found in the project URL in Ahrefs\) |
| `date` | string | No | Crawl date in YYYY-MM-DDThh:mm:ss format \(defaults to the most recent crawl\) |
| `limit` | number | No | Maximum number of results to return. Example: 50 \(default: 1000\) |
| `offset` | number | No | Number of results to skip, for pagination |
| `issueId` | string | No | Only return pages affected by this issue ID |
| `apiKey` | string | Yes | Ahrefs API Key |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `auditPages` | array | List of crawled pages with health and SEO metrics |
| ↳ `url` | string | The crawled page URL |
| ↳ `httpCode` | number | HTTP status code returned by the URL |
| ↳ `title` | array | Page title tag\(s\) |
| ↳ `internalLinks` | number | Number of internal outgoing links |
| ↳ `externalLinks` | number | Number of external outgoing links |
| ↳ `backlinks` | number | Number of incoming external links to the page |
| ↳ `compliant` | boolean | Whether the page is indexable \(200 status, no canonical/noindex\) |
| ↳ `traffic` | number | Estimated monthly organic traffic to the page |
### `ahrefs_rank_tracker_overview`
Get ranking overview metrics for the keywords tracked in an Ahrefs Rank Tracker project: position, search volume, keyword difficulty, and estimated traffic. This endpoint is free and does not consume API units.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `projectId` | number | Yes | The Rank Tracker project ID \(found in the project URL in Ahrefs\) |
| `date` | string | Yes | Date to report rankings for, in YYYY-MM-DD format |
| `device` | string | Yes | Rankings device type: "desktop" or "mobile" |
| `dateCompared` | string | No | Comparison date in YYYY-MM-DD format, to compute position/traffic deltas |
| `volumeMode` | string | No | Search volume calculation: "monthly" or "average" \(default: "monthly"\) |
| `limit` | number | No | Maximum number of results to return. Example: 50 \(default: 1000\) |
| `apiKey` | string | Yes | Ahrefs API Key |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `overviews` | array | Ranking overview for each tracked keyword |
| ↳ `keyword` | string | The tracked keyword |
| ↳ `position` | number | Top organic search position |
| ↳ `volume` | number | Average monthly search volume |
| ↳ `keywordDifficulty` | number | Keyword difficulty score \(0-100\) |
| ↳ `url` | string | Top-ranking URL |
| ↳ `traffic` | number | Estimated monthly organic visits |
| ↳ `serpFeatures` | array | SERP features present in the results |
| ↳ `bestPositionKind` | string | Type of the top position \(organic, paid, or SERP feature\) |
### `ahrefs_rank_tracker_serp_overview`
Get the full SERP (search engine results page) for a keyword tracked in an Ahrefs Rank Tracker project, including every ranking URL with its position, title, and authority metrics. This endpoint is free and does not consume API units.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `projectId` | number | Yes | The Rank Tracker project ID \(found in the project URL in Ahrefs\) |
| `keyword` | string | Yes | The tracked keyword to retrieve SERP data for |
| `country` | string | Yes | Country code for the tracked keyword. Example: "us", "gb", "de" |
| `device` | string | Yes | Rankings device type: "desktop" or "mobile" |
| `topPositions` | number | No | Number of top organic positions to return \(defaults to all available\) |
| `date` | string | No | Timestamp to return the last available SERP Overview at, in YYYY-MM-DDThh:mm:ss format |
| `locationId` | number | No | Location ID of the tracked keyword, if tracked at a specific location |
| `languageCode` | string | No | Language code of the tracked keyword |
| `apiKey` | string | Yes | Ahrefs API Key |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `positions` | array | Every ranking result on the SERP for the tracked keyword |
| ↳ `position` | number | Position of the result in the SERP |
| ↳ `url` | string | URL of the ranking page |
| ↳ `title` | string | Page title |
| ↳ `type` | array | The kind of the position: organic, paid, or a SERP feature |
| ↳ `domainRating` | number | Domain Rating of the ranking domain |
| ↳ `urlRating` | number | URL Rating of the ranking page |
| ↳ `backlinks` | number | Total backlinks to the ranking domain |
| ↳ `refdomains` | number | Unique referring domains |
| ↳ `traffic` | number | Estimated monthly organic search traffic |
| ↳ `value` | number | Estimated monthly traffic value \(USD\) |
| ↳ `topKeyword` | string | Highest-traffic keyword ranking for this page |
| ↳ `topKeywordVolume` | number | Monthly search volume for the top keyword |
| ↳ `updateDate` | string | Date the SERP was last checked |
### `ahrefs_rank_tracker_competitors_overview`
Get competitor rankings for the keywords tracked in an Ahrefs Rank Tracker project: each tracked keyword's volume and difficulty alongside every competitor's position, traffic, and traffic value. This endpoint is free and does not consume API units.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `projectId` | number | Yes | The Rank Tracker project ID \(found in the project URL in Ahrefs\) |
| `date` | string | Yes | Date to report rankings for, in YYYY-MM-DD format |
| `device` | string | Yes | Rankings device type: "desktop" or "mobile" |
| `dateCompared` | string | No | Comparison date in YYYY-MM-DD format, to compute position/traffic deltas |
| `volumeMode` | string | No | Search volume calculation: "monthly" or "average" \(default: "monthly"\) |
| `limit` | number | No | Maximum number of results to return. Example: 50 \(default: 1000\) |
| `apiKey` | string | Yes | Ahrefs API Key |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `competitorKeywords` | array | Tracked keywords with competitor ranking data |
| ↳ `keyword` | string | The tracked keyword |
| ↳ `volume` | number | Average monthly search volume |
| ↳ `keywordDifficulty` | number | Keyword difficulty score \(0-100\) |
| ↳ `serpFeatures` | array | SERP features present in the results |
| ↳ `competitorsList` | array | Ranking data for each tracked competitor on this keyword |
| ↳ `url` | string | The competitor's ranking URL |
| ↳ `position` | number | Current ranking position |
| ↳ `bestPositionKind` | string | Type of the best position achieved |
| ↳ `traffic` | number | Estimated traffic to the competitor |
| ↳ `value` | number | Estimated traffic value \(USD\) |
### `ahrefs_rank_tracker_competitors_stats`
Get aggregate competitor stats for an Ahrefs Rank Tracker project: each competitor's traffic, traffic value, average position, and share of voice across all tracked keywords. This endpoint is free and does not consume API units.
#### Input
| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `projectId` | number | Yes | The Rank Tracker project ID \(found in the project URL in Ahrefs\) |
| `date` | string | Yes | Date to report metrics for, in YYYY-MM-DD format |
| `device` | string | Yes | Rankings device type: "desktop" or "mobile" |
| `volumeMode` | string | No | Search volume calculation: "monthly" or "average" \(default: "monthly"\) |
| `apiKey` | string | Yes | Ahrefs API Key |
#### Output
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `competitorsStats` | array | Aggregate stats for each tracked competitor |
| ↳ `competitor` | string | The competitor's URL |
| ↳ `traffic` | number | Estimated monthly organic visits |
| ↳ `trafficValue` | number | Estimated monthly organic traffic value \(USD\) |
| ↳ `averagePosition` | number | Average top organic position across tracked keywords |
| ↳ `pos1To3` | number | Keywords ranking in top 3 positions |
| ↳ `pos4To10` | number | Keywords ranking in positions 4-10 |
| ↳ `shareOfVoice` | number | Organic traffic share percentage |
| ↳ `shareOfTrafficValue` | number | Organic traffic value share percentage |