# POST /v1/keywords/ideas

Related keyword ideas for a seed set, with volume, CPC and competition.

**Credits:** 110 credits per call.

**Timeout:** 60s

## Parameters

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `keywords` | array | yes | — | Seed keywords to expand from. Required, 1-20 seeds, each max 700 chars. Array of string. Max 20 items. |
| `location` | any | no | 2840 | Google Ads geotarget ID, an ISO country code (e.g. "US"), or a country name. Optional, default 2840 (United States). Look one up with /v1/locations. |
| `language` | string | no | "en" | ISO language code. Optional, default "en". |
| `limit` | integer | no | 50 | Max ideas to return. Optional, default 50. 1-200. |

## Request

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

{
  "keywords": [
    "running shoes"
  ],
  "location": 2840,
  "language": "en",
  "limit": 50
}
```

## 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_vske6iutevl7pcftmjfdzqim",
  "request_id": "req_jyn33sts2bkfbg7u6y3mzdeqn4",
  "object": "keyword_ideas",
  "created_at": "2026-07-29T12:00:00Z",
  "elapsed_ms": 180,
  "cache": "miss",
  "credits": {
    "charged": 110,
    "balance": 9857
  },
  "data": {
    "items_count": 3,
    "items": [
      {
        "keyword": "best running shoes",
        "search_volume": 74000,
        "cpc": 0.91,
        "competition": 0.42
      },
      {
        "keyword": "trail running shoes",
        "search_volume": 33100,
        "cpc": 1.14,
        "competition": 0.55
      },
      {
        "keyword": "running shoes for flat feet",
        "search_volume": 12100,
        "cpc": 0.78,
        "competition": 0.37
      },
      "…"
    ]
  }
}
```

## Response fields

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

| Field | Description |
| --- | --- |
| `data.items_count` | Number of ideas returned. |
| `data.items` | Related keyword ideas for your seed set, volume-ranked. |
| `data.items[].keyword` | The idea keyword. |
| `data.items[].search_volume` | Average monthly searches, or null if unknown. |
| `data.items[].cpc` | Average cost-per-click in USD, or null if unknown. |
| `data.items[].competition` | Advertiser competition 0-1, or null if unknown. |