docs / endpoint

POST /v1/keywords/questions

People-Also-Ask questions observed for a topic, deduplicated.

Credits: 20 credits per call. Timeout: 60s

Parameters

NameTypeRequiredDefaultDescription
keyword string required — Topic keyword to fetch People-Also-Ask questions for. Required, max 700 chars.
location any optional 2840 Google Ads geotarget ID. 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 Optional, default 50. 1-200.

Request

→ requestPOST /v1/keywords/questions
POST /v1/keywords/questions HTTP/1.1
Authorization: Bearer sof_live_your_key_here
Content-Type: application/json

{
  "keyword": "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_lqex65mztezj7b2vliioz5fv",
  "request_id": "req_ahrnchlbsvhgdhq47jggyg746u",
  "object": "keyword_questions",
  "created_at": "2026-08-09T07:21:58Z",
  "elapsed_ms": 180,
  "cache": "miss",
  "credits": {
    "charged": 20,
    "balance": 9857
  },
  "data": {
    "keyword": "running shoes",
    "items": [
      {
        "question": "How often should you replace running shoes?",
        "first_seen": "2026-06-11",
        "last_seen": "2026-07-25",
        "times_seen": 18
      },
      {
        "question": "Are carbon plate shoes worth it?",
        "first_seen": "2026-07-02",
        "last_seen": "2026-07-27",
        "times_seen": 7
      },
      "…"
    ],
    "count": 42,
    "coverage": {
      "from": "2026-07-01",
      "observations": 130
    }
  }
}

Response fields

What each field in data (above) means.

FieldDescription
data.keyword The keyword you requested.
data.items People-Also-Ask questions observed for this keyword, up to limit.
data.items[].question The question text.
data.items[].first_seen Date this question was first observed.
data.items[].last_seen Date this question was last observed.
data.items[].times_seen Number of times this question has been observed.
data.count Total number of distinct questions found, before limit truncation.
data.coverage How much of the archive this response drew from.
data.coverage.from Earliest date the archive could have observed, floor-clamped to the archive's retention window.
data.coverage.observations Number of times we checked for this keyword in the window -- can be > 0 even when items is empty.