# POST /v1/keywords/volume

Historical Google keyword search volume and competition metrics.

**Credits:** 20 credits per call.

**Timeout:** 60s

## Parameters

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `keywords` | array | yes | — | Keywords to fetch search volume for. Required, non-empty. Array of string. Max 500 items. |
| `location` | any | yes | — | Google Ads geotarget ID, or a location name (e.g. a country/state/city name). Required. Look one up with /v1/locations. |
| `language` | string | yes | — | ISO language code. Required. |
| `search_partners` | boolean | no | false | Include Google Search Network partner sites in the volume figures. Optional, default false. |
| `tag` | string | no | — | Optional client-defined label forwarded to the upstream job for your own bookkeeping; not echoed back in the response. |

## Request

```http
POST /v1/keywords/volume HTTP/1.1
Authorization: Bearer sof_live_your_key_here
Content-Type: application/json

{
  "keywords": [
    "running shoes",
    "trail running shoes"
  ],
  "location": "US",
  "language": "en"
}
```

## Response

Wrapped in the standard envelope (id, object, created_at, elapsed_ms, cache, credits) -- documented once on The Contract. The body below is a real envelope with this endpoint's `data` shape; values vary per request, and a `…` marks an array cut short for display.

```json
{
  "id": "keyw_n5g2uehiv5flaqsm23kni7ou",
  "request_id": "req_4cciudifqfggtgdcxbd54vb5oa",
  "object": "keyword_volume",
  "created_at": "2026-08-09T08:30:31Z",
  "elapsed_ms": 180,
  "cache": "miss",
  "credits": {
    "charged": 20,
    "balance": 9857
  },
  "data": {
    "location": {
      "code": 2840,
      "name": "United States"
    },
    "language": {
      "code": "en",
      "name": "English"
    },
    "network": "google_search",
    "items_count": 2,
    "items": [
      {
        "keyword": "running shoes",
        "avg_monthly_searches": 90500,
        "competition": "HIGH",
        "competition_index": 88,
        "cpc": 1.24,
        "low_bid": 0.42,
        "high_bid": 2.1,
        "monthly": [
          {
            "month": "2026-06",
            "search_volume": 91000
          },
          "…"
        ]
      },
      {
        "keyword": "trail running shoes",
        "avg_monthly_searches": 8100,
        "competition": "MEDIUM",
        "competition_index": 54,
        "cpc": 0.87,
        "low_bid": 0.31,
        "high_bid": 1.55,
        "monthly": [
          {
            "month": "2026-06",
            "search_volume": 8300
          },
          "…"
        ]
      }
    ]
  }
}
```

## Response fields

What each field in `data` (above) means.

| Field | Description |
| --- | --- |
| `data.location` | Resolved geotarget for this call. |
| `data.location.code` | Google Ads geotarget ID. |
| `data.location.name` | Human-readable geotarget name. |
| `data.language` | Resolved language for this call. |
| `data.language.code` | ISO language code. |
| `data.language.name` | Human-readable language name. |
| `data.network` | Search network the volume figures are drawn from, e.g. "google_search". |
| `data.items_count` | Number of entries in items. |
| `data.items` | One row per requested keyword. |
| `data.items[].keyword` | The keyword. |
| `data.items[].avg_monthly_searches` | Average monthly search volume over the trailing 12 months. |
| `data.items[].competition` | Advertiser competition level: LOW, MEDIUM, or HIGH. |
| `data.items[].competition_index` | 0-100 advertiser competition score (finer-grained than competition). |
| `data.items[].cpc` | Average cost-per-click for advertisers bidding on this keyword. |
| `data.items[].low_bid` | Low end of the typical top-of-page bid range. |
| `data.items[].high_bid` | High end of the typical top-of-page bid range. |
| `data.items[].monthly` | Month-by-month search volume history. |
| `data.items[].monthly[].month` | Month this row covers, YYYY-MM. |
| `data.items[].monthly[].search_volume` | Search volume for that month. |