Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Get a time series for a domain or URL from Ahrefs Site Explorer: organic and paid traffic and value, ranking keywords by position bucket, referring domains, Domain Rating, URL Rating, ranking pages…
| App | Ahrefs |
| Operation ID | ahrefs_get_metrics_history |
| 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 get history for (e.g. example.com). url_rating needs a page URL. |
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). Ignored for domain_rating and url_rating. |
metric_group | string or SelectableOption | No | traffic_and_cost | Which history to return: ‘traffic_and_cost’ (org_traffic, org_cost, paid_traffic, paid_cost; 10 units per metric per row), ‘keywords_by_position’ (ranking keywords in top3, top4_10, top11_20, top21_50, top51_plus), ‘referring_domains’ (5 units per row), ‘domain_rating’, ‘url_rating’, ‘pages’ (ranking pages), or ‘total_search_volume’ (10 units per row). |
country | string or SelectableOption | No | - | Two-letter country code to restrict to one country. Leave empty for all countries. Applies to traffic_and_cost, keywords_by_position, pages and total_search_volume. |
date_from | string | Yes | - | Start of the period in YYYY-MM-DD format. |
date_to | string | No | - | End of the period in YYYY-MM-DD format. Defaults to today. |
grouping | string or SelectableOption | No | monthly | Time interval of the data points: ‘monthly’ (default), ‘weekly’ or ‘daily’. Every data point is a billed row. |
page_positions | string or SelectableOption | No | top100 | For metric_group ‘pages’: count pages ranking in the ‘top100’ (default) or only the ‘top10’. |
top_positions | string or SelectableOption | No | top_10 | For metric_group ‘total_search_volume’: sum the volume of keywords the target ranks for in the ‘top_10’ (default) or ‘top_100’. |
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
value | string | Yes | - | |
label | string | Yes | - |
List[Dict]
Returns one row per period with date plus the metric group’s fields: org_traffic, org_cost (USD), paid_traffic, paid_cost (USD) | top3, top4_10, top11_20, top21_50, top51_plus | refdomains | domain_rating | url_rating | pages | total_search_volume.
Fields: date, org_traffic, org_cost, paid_traffic, paid_cost
Example:
[
{
"date": "2026-07-01T00:00:00Z",
"org_traffic": 2396849,
"org_cost": 4613286.26,
"paid_traffic": 8612,
"paid_cost": 36468.81
},
{
"date": "2026-08-01T00:00:00Z",
"org_traffic": 4589171,
"org_cost": 6562258.57,
"paid_traffic": 531,
"paid_cost": 1349.93
}
]