> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markifact.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Metrics History

> 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...

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, or total search volume, grouped daily, weekly or monthly. Every data point is a billed row (10 units per traffic or cost metric, 5 for referring domains, 1 otherwise).

|                      |                              |
| -------------------- | ---------------------------- |
| **App**              | Ahrefs                       |
| **Operation ID**     | `ahrefs_get_metrics_history` |
| **Type**             | Action                       |
| **Connection**       | `ahrefs` (required)          |
| **Credits per run**  | Free                         |
| **Agent / MCP tool** | Yes                          |

## Inputs

| 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'.                                                                                                                                                                                                                                                |

### SelectableOption

| Field   | Type   | Required | Default | Description |
| ------- | ------ | -------- | ------- | ----------- |
| `value` | string | Yes      | -       |             |
| `label` | string | Yes      | -       |             |

## Output

**Type**: `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**:

```json theme={"dark"}
[
  {
    "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
  }
]
```