Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
List the pages of a domain or subfolder that get the most organic search traffic in Ahrefs Site Explorer, with keyword counts, traffic, traffic value, top keyword, URL Rating and referring domains
| App | Ahrefs |
| Operation ID | ahrefs_get_top_pages |
| Type | Action |
| Connection | ahrefs (required) |
| Credits per run | Free |
| Agent / MCP tool | Yes |
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
target | string | Yes | - | The domain, subdomain, subfolder or URL to list top organic pages for (e.g. example.com, example.com/blog/). |
mode | string or SelectableOption | No | subdomains | How to interpret the target: ‘subdomains’ (domain and all subdomains, default), ‘domain’ (the exact host only), ‘prefix’ (every URL starting with the target), or ‘exact’ (the exact URL only). |
country | string or SelectableOption | No | - | Two-letter country code (e.g. us, gb, de) to restrict results to one country. Leave empty for all countries. |
date | string | No | - | Report date in YYYY-MM-DD format. Defaults to today (latest data). |
date_compared | string | No | - | Optional earlier date in YYYY-MM-DD format to compare against; enables the *_prev and *_diff metrics. |
metrics | array of string or SelectableOption | No | - | Metrics to return (url is always included). Available: keywords, keywords_prev, keywords_diff, keywords_diff_percent, sum_traffic, sum_traffic_prev, traffic_diff, traffic_diff_percent, value (USD), value_prev, value_diff, value_diff_percent, top_keyword, top_keyword_volume, top_keyword_best_position, top_keyword_country, ur, referring_domains, page_type, status (needs date_compared). For AI citation counts per page use ahrefs_get_domain_overview with the page URLs as targets, mode ‘exact’ and include_ai_citations. Ahrefs API unit cost per row: sum_traffic, sum_traffic_prev, value, value_prev and top_keyword_volume cost 10 units, referring_domains 5, the rest 1. Defaults to keywords, sum_traffic, value, top_keyword, top_keyword_best_position, ur, referring_domains. |
filters | array of FilterItem | No | - | Filters on the available metrics, e.g. sum_traffic GREATER_THAN 100 or url CONTAINS ‘/blog/’. Filter fields count towards the unit cost per row. |
orders | array of OrderItem | No | - | Sort by one or more metrics. |
limit | integer | No | 100 | Maximum number of rows to return. Defaults to 100. Your Ahrefs plan caps rows per request (Lite 100, Standard 250, Advanced 500). |
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
field | string or SelectableOption | Yes | - | The field to filter on, must be one of the current selected metrics or dimensions. |
operator | string | Yes | - | The operator to use for filtering. Must be one of the supported values. Use REGEXP_MATCH to search/filter by multiple OR values like ’.(summer|holiday).’ |
value | string | Yes | - | The value to filter by, always as a string: text, a number, or a regex. For IN_LIST and NOT_IN_LIST, pass the values as one comma-separated string such as ‘a,b,c’, not as an array. For regex values, escape backslashes once in the JSON string: write \b for a word boundary, not \b. |
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
field | string or SelectableOption | Yes | - | The field to sort by. must be one of the current selected metrics or dimensions. |
direction | string | Yes | - | The order to sort by, must be one of ‘ASC’, ‘DESC’ |
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
value | string | Yes | - | |
label | string | Yes | - |
List[Dict]
Returns one row per page with the selected Ahrefs fields: url, keywords, sum_traffic, value (USD), top_keyword, top_keyword_volume, top_keyword_best_position, ur, referring_domains, page_type and *_prev / *_diff comparison fields.
Fields: url, keywords, sum_traffic, value, top_keyword, top_keyword_best_position, ur, referring_domains
Example:
[
{
"url": "https://ahrefs.com/backlink-checker",
"keywords": 1411,
"sum_traffic": 3114948,
"value": 520661.27,
"top_keyword": "backlink checker",
"top_keyword_best_position": 1
}
]