docs / endpoint

POST /v1/keywords/ideas

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

Credits: 110 credits per call. Timeout: 60s

Parameters

NameTypeRequiredDefaultDescription
keywords array required — Seed keywords to expand from. Required, 1-20 seeds, each max 700 chars. Array of string. Max 20 items.
location any optional 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 optional "en" ISO language code. Optional, default "en".
limit integer optional 50 Max ideas to return. Optional, default 50. 1-200.

Request

→ requestPOST /v1/keywords/ideas
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.

← response200
{
  "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.

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