# Get search volume, CPC and competition for keywords

Returns monthly search volume, CPC and competition for up to 1,000 keywords in one call. Use it to size keywords you already have.

Tool `google.keywords.volume` on Google. Contract version 1, released 2026-10-27.

## Example call

Over REST, send the input in the body. Over MCP, pass the same input to `call_tool`.

cURL:

```bash
curl https://api.voxoria.ai/v1/tools/google.keywords.volume/calls \
  -H "Authorization: Bearer $VOXORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"keywords":["crm software","project management software"],"country":"gb"}}'
```

Python:

```python
import os

import httpx

response = httpx.post(
    "https://api.voxoria.ai/v1/tools/google.keywords.volume/calls",
    headers={"Authorization": f"Bearer {os.environ['VOXORIA_API_KEY']}"},
    json={
        "input": {
            "keywords": ["crm software", "project management software"],
            "country": "gb",
        },
    },
    timeout=60,
)
print(response.json())
```

TypeScript:

```ts
const response = await fetch("https://api.voxoria.ai/v1/tools/google.keywords.volume/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VOXORIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "input": {
      "keywords": ["crm software", "project management software"],
      "country": "gb",
    },
  }),
});
console.log(await response.json());
```

MCP (`tools/call` params):

```json
{
  "name": "call_tool",
  "arguments": {
    "tool": "google.keywords.volume",
    "input": {
      "keywords": [
        "crm software",
        "project management software"
      ],
      "country": "gb"
    }
  }
}
```

Both return [the full response](/docs/call-response.md): the call's ID, status and cost, with this tool's result in `output`.

## Input

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `keywords` | array of string | Yes |  | The keywords to look up, up to 1000 in one call at one price. Each is at most 80 characters and 10 words. Case-insensitive. No keyword twice. Google Ads refuses some symbols and emojis. Each item: 1 to 80 characters. Each item: matches `^\s*\S+(\s+\S+){0,9}\s*$`. 1 to 1000 items. No item twice. |
| `country` | string | No | `us` | Two-letter ISO 3166-1 country code. Case-insensitive. One of the 249 values of the `countries` list: ISO 3166-1 alpha-2 country codes, lowercase. |
| `language` | string | No | `en` | Two-letter ISO 639-1 language code. Case-insensitive. One of the 184 values of the `languages` list: ISO 639-1 two-letter language codes, lowercase. |

## Output

A successful call returns these blocks in its `output`. A field not marked required can be `null`.

### results

A list of rows. Always present, possibly empty.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `keyword` | string | Yes |  |
| `search_volume` | integer | No | Average monthly Google searches in the country. |
| `monthly_searches` | array of object | No | Google searches in the country in each recent month, usually the last 12. |
| `monthly_searches.year` | integer | Yes |  |
| `monthly_searches.month` | integer | Yes | Month of the year, from 1 (January) to 12. |
| `monthly_searches.search_volume` | integer | Yes |  |
| `cpc` | number | No | Average cost per click in Google Ads, in USD. |
| `competition_level` | string | No | Advertiser competition for the keyword in Google Ads, as a band. One of `low`, `medium`, `high`. |
| `competition_index` | integer | No | The same competition as Google Ads' index, from 0 (none) to 100 (highest). |

## Example output

The `output` of a real call, each list cut to 3 items.

```json
{
  "results": [
    {
      "keyword": "crm software",
      "search_volume": 8100,
      "monthly_searches": [
        {
          "year": 2026,
          "month": 9,
          "search_volume": 18100
        },
        {
          "year": 2026,
          "month": 8,
          "search_volume": 14800
        },
        {
          "year": 2026,
          "month": 7,
          "search_volume": 9900
        }
      ],
      "cpc": 22.73,
      "competition_level": "low",
      "competition_index": 28
    },
    {
      "keyword": "project management software",
      "search_volume": 6600,
      "monthly_searches": [
        {
          "year": 2026,
          "month": 9,
          "search_volume": 18100
        },
        {
          "year": 2026,
          "month": 8,
          "search_volume": 14800
        },
        {
          "year": 2026,
          "month": 7,
          "search_volume": 9900
        }
      ],
      "cpc": 43.73,
      "competition_level": "low",
      "competition_index": 21
    }
  ]
}
```