Keyword Volume API: Estimate a keyword list

Overview

Estimate a whole keyword list for a brand: each keyword’s weekly US AI prompt volume, its Demand Score and its Commercial Intent score, the same numbers the Keyword Volume page in Scrunch shows. A list runs in the background. You start it, then poll it until it’s done; each keyword’s numbers appear as soon as it finishes.

Keyword Volume has to be on for your brand. Talk to your Scrunch team to turn it on. Until it’s on, every endpoint returns 404.

How it works

Start a list of up to 200 keywords. You get its id back at once.
Get the list about every 30 seconds until its status is finished, failed or canceled. Each keyword’s numbers appear as soon as it’s done, and stay readable after the list ends.
Cancel it if you started the wrong list. Keywords not yet estimated give their lookups back.

All endpoints live under https://api.scrunchai.com/v1.

Method	Path	What it does
`POST`	`/{brand_id}/keyword-volume/lists`	Start a list.
`GET`	`/{brand_id}/keyword-volume/lists/{list_id}`	A list’s status and every keyword on it, with results.
`POST`	`/{brand_id}/keyword-volume/lists/{list_id}/cancel`	Stop a running list.

A brand runs one list at a time. A list of new keywords takes a few minutes; keywords estimated recently come back almost at once.

Authentication

Send an API key as a Bearer token. Create one in Scrunch under API Keys. Every endpoint needs the query scope.

export SCRUNCH_API_TOKEN="your-key"

Start a list

curl -X POST "https://api.scrunchai.com/v1/1234/keyword-volume/lists" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["crm for small business", "email marketing tools", "project management software"]}'

Up to 200 keywords, each up to 200 characters.
Repeats (ignoring case and spacing) are counted once, and blank entries are dropped.

The response (202) is the list, with its id and how many keywords are in each status:

{
  "id": 4182,
  "status": "queued",
  "country": "US",
  "item_count": 3,
  "counts": { "pending": 3, "running": 0, "done": 0, "failed": 0, "skipped_weekly_limit": 0, "canceled": 0 },
  "created_at": "2026-11-09T21:58:20Z",
  "started_at": null,
  "finished_at": null
}

Get the list

curl "https://api.scrunchai.com/v1/1234/keyword-volume/lists/4182" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN"

{
  "id": 4182,
  "status": "finished",
  "country": "US",
  "item_count": 3,
  "counts": { "pending": 0, "running": 0, "done": 3, "failed": 0, "skipped_weekly_limit": 0, "canceled": 0 },
  "created_at": "2026-11-09T21:58:20Z",
  "started_at": "2026-11-09T21:58:20Z",
  "finished_at": "2026-11-09T22:00:36Z",
  "items": [
    {
      "position": 0,
      "keyword": "crm for small business",
      "status": "done",
      "result": {
        "weekly_estimate": 9719.0,
        "estimated": false,
        "demand_score": 50,
        "demand_label": "Medium",
        "commercial_intent_score": 97,
        "degraded": false
      }
    },
    {
      "position": 1,
      "keyword": "email marketing tools",
      "status": "done",
      "result": {
        "weekly_estimate": 9735.0,
        "estimated": false,
        "demand_score": 50,
        "demand_label": "Medium",
        "commercial_intent_score": 91,
        "degraded": false
      }
    },
    {
      "position": 2,
      "keyword": "project management software",
      "status": "done",
      "result": {
        "weekly_estimate": 8241.0,
        "estimated": false,
        "demand_score": 47,
        "demand_label": "Medium",
        "commercial_intent_score": 87,
        "degraded": false
      }
    }
  ]
}

The list’s status is queued (waiting to start), running, finished, failed (stopped early) or canceled. Each keyword’s status is one of:

Status	Meaning
`pending`	Waiting to run.
`running`	Being estimated now.
`done`	Finished. `result` holds its numbers.
`failed`	Couldn’t be estimated. Its weekly lookup was given back.
`skipped_weekly_limit`	Not run: the brand’s weekly lookups ran out.
`canceled`	Not run: the list was canceled or stopped first.

Result fields

Field	Type	Description
`weekly_estimate`	number or null	Estimated weekly US AI prompt volume for the keyword.
`estimated`	boolean	`true` when there was too little direct evidence for a reading, so `weekly_estimate` is modeled.
`demand_score`	integer or null	Weekly volume on a 1 to 100 log scale: 50 is about 10,000 prompts a week. `0` when there is no demand.
`demand_label`	string or null	The Demand Score’s band: `No demand`, `Very Low`, `Low`, `Medium`, `High` or `Very High`.
`commercial_intent_score`	integer or null	How buying-oriented the prompts for the keyword are, from 0 to 100. Higher means more commercial than AI prompts in general. Null when there wasn’t enough to score.
`degraded`	boolean	`true` when part of the estimate couldn’t run, so the numbers may read low. Estimate the keyword again later.

weekly_estimate, demand_score and demand_label are null together when a keyword couldn’t be measured.

Cancel a list

curl -X POST "https://api.scrunchai.com/v1/1234/keyword-volume/lists/4182/cancel" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN"

Keywords not yet estimated become canceled and their weekly lookups are given back. Finished keywords keep their results. Canceling a list that has already ended changes nothing.

Weekly lookups

Keyword Volume has a weekly allowance of lookups per brand, shared with lookups made in Scrunch itself.

Each keyword that hasn’t been estimated recently uses one lookup. Keywords estimated recently run without using one.
A list bigger than what’s left isn’t refused. The keywords past the limit are marked skipped_weekly_limit, in list order, and the rest run.
Lookups come back for a keyword that fails, is canceled, or turns out to have been estimated recently after all.

Status codes

Status	Meaning
`200`	The list, with its keywords.
`202`	The list was started or canceled.
`401`	The API key is missing, unknown or disabled.
`403`	The key lacks the `query` scope, or can’t access the brand.
`404`	The brand or list doesn’t exist, or Keyword Volume isn’t on for the brand.
`409`	The brand already has a list running. `detail.job_id` in the body is that list: poll it or cancel it.
`422`	The request isn’t valid: no keywords, more than 200, or a keyword longer than 200 characters.
`429`	No keyword on the list fits this week’s lookups. Nothing was started or charged.
`503`	The list couldn’t be started. Nothing was charged; try again.

Tips

Poll every 30 seconds or so. Results land keyword by keyword; there’s no need to poll faster.
Lost the id? While the list runs, starting another returns 409 with the running list’s id at detail.job_id.
Want a spreadsheet? Each keyword’s numbers are in items[].result; write them out as CSV on your side.
Use the MCP server instead if you’re working in an AI assistant: start_keyword_list, get_keyword_list and cancel_keyword_list do the same thing.

Measure

Optimize

Deliver

Configure

Deprecated

Keyword Volume API: Estimate a keyword list

Overview

How it works

Authentication

Start a list

Get the list

Result fields

Cancel a list

Weekly lookups

Status codes

Tips

​Overview

​How it works

​Authentication

​Start a list

​Get the list

​Result fields

​Cancel a list

​Weekly lookups

​Status codes

​Tips

Overview

How it works

Authentication

Start a list

Get the list

Result fields

Cancel a list

Weekly lookups

Status codes

Tips