> ## Documentation Index
> Fetch the complete documentation index at: https://developers.scrunch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Keyword Volume API: Estimate a keyword list

> Estimate weekly US AI prompt volume, Demand Score and Commercial Intent for up to 200 keywords at once: start a list, then read its results as they finish.

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

> [!WARNING]
>
> 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

1. **Start a list** of up to 200 keywords. You get its `id` back at once.
2. **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.
3. **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.

```bash theme={null}
export SCRUNCH_API_TOKEN="your-key"
```

***

## Start a list

```bash theme={null}
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:

```json theme={null}
{
  "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

```bash theme={null}
curl "https://api.scrunchai.com/v1/1234/keyword-volume/lists/4182" \
  -H "Authorization: Bearer $SCRUNCH_API_TOKEN"
```

```json theme={null}
{
  "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

```bash theme={null}
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`](https://developers.scrunch.com/mcp/tools#start-keyword-list), [`get_keyword_list`](https://developers.scrunch.com/mcp/tools#get-keyword-list) and [`cancel_keyword_list`](https://developers.scrunch.com/mcp/tools#cancel-keyword-list) do the same thing.


## Related topics

- [Get Keyword List](https://developers.scrunch.com/api-reference/keyword-volume/get-keyword-list.md)
- [Cancel Keyword List](https://developers.scrunch.com/api-reference/keyword-volume/cancel-keyword-list.md)
- [Start Keyword List](https://developers.scrunch.com/api-reference/keyword-volume/start-keyword-list.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.