> ## 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 Keyword Volume History

> Get search volume trends for keywords from Ahrefs Keywords Explorer: monthly volume in one country over a period (seasonality), or average monthly volume per country (market sizing)

Get search volume trends for keywords from Ahrefs Keywords Explorer: monthly volume in one country over a period (seasonality), or average monthly volume per country (market sizing). One request per keyword.

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

## Inputs

| Field       | Type                       | Required | Default   | Description                                                                                                                                              |
| ----------- | -------------------------- | -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `keywords`  | array of string or string  | Yes      | -         | Keywords to look up. Accepts a list or a newline/comma-separated string. One Ahrefs request per keyword (minimum 50 API units each).                     |
| `breakdown` | string or SelectableOption | No       | `monthly` | 'monthly' (default): search volume per month in one country over a period. 'by\_country': average monthly volume per country (10 units per country row). |
| `country`   | string or SelectableOption | No       | `us`      | Two-letter country code for the monthly breakdown (e.g. us, gb, de). Defaults to us. Ignored for by\_country.                                            |
| `date_from` | string                     | No       | -         | Monthly breakdown: start month in YYYY-MM-DD format. Leave empty for the full history Ahrefs has.                                                        |
| `date_to`   | string                     | No       | -         | Monthly breakdown: end month in YYYY-MM-DD format. Defaults to the latest month.                                                                         |
| `limit`     | integer                    | No       | -         | by\_country: maximum number of countries per keyword, largest first. Leave empty for all.                                                                |

### SelectableOption

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

## Output

**Type**: `List[Dict]`

Returns one row per keyword and month (keyword, date, volume) for the monthly breakdown, or per keyword and country (keyword, country, volume) for by\_country.

**Fields**: `keyword`, `date`, `volume`

**Example**:

```json theme={"dark"}
[
  {
    "keyword": "ahrefs",
    "date": "2026-07-01T00:00:00Z",
    "volume": 80770
  },
  {
    "keyword": "ahrefs",
    "date": "2026-08-01T00:00:00Z",
    "volume": 77317
  }
]
```