> ## 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. # Start Keyword List > Start estimating a list of up to 200 keywords. The list runs in the background: poll Get Keyword List for each keyword's weekly volume, Demand Score and Commercial Intent score as they finish. Repeated keywords are counted once. Each keyword that hasn't been estimated recently uses one of the brand's weekly lookups. When the list needs more than the brand has left, the keywords past the limit are skipped (status `skipped_weekly_limit`) rather than the list being refused; recently estimated keywords always run, and use no lookup. A keyword that fails gives its lookup back. A brand runs one list at a time. ## OpenAPI ````yaml /api-reference/openapi.json post /{brand_id}/keyword-volume/lists openapi: 3.1.0 info: title: Scrunch Data API version: 0.1.0 servers: - url: https://api.scrunchai.com/v1 security: [] paths: /{brand_id}/keyword-volume/lists: post: tags: - keyword-volume summary: Start Keyword List description: >- Start estimating a list of up to 200 keywords. The list runs in the background: poll Get Keyword List for each keyword's weekly volume, Demand Score and Commercial Intent score as they finish. Repeated keywords are counted once. Each keyword that hasn't been estimated recently uses one of the brand's weekly lookups. When the list needs more than the brand has left, the keywords past the limit are skipped (status `skipped_weekly_limit`) rather than the list being refused; recently estimated keywords always run, and use no lookup. A keyword that fails gives its lookup back. A brand runs one list at a time. operationId: startKeywordList parameters: - name: brand_id in: path required: true schema: type: integer description: The unique identifier for the brand title: Brand Id description: The unique identifier for the brand requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/KeywordBulkRequest' responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/KeywordBulkJob' '409': description: >- The brand already has a keyword list running. `detail.job_id` is that list: poll it or cancel it. content: application/json: schema: $ref: '#/components/schemas/KeywordBulkActiveResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: No keyword on the list fits this week's lookups. '503': description: The list could not be started. Nothing was charged. security: - HTTPBearer: - query components: schemas: KeywordBulkRequest: properties: keywords: items: type: string maxLength: 200 type: array maxItems: 200 minItems: 1 title: Keywords description: >- Up to 200 keywords, each up to 200 characters. Repeats (ignoring case and spacing) are counted once, and blank entries are dropped. type: object required: - keywords title: KeywordBulkRequest description: A list of keywords to estimate in the background. KeywordBulkJob: properties: id: type: integer title: Id description: The list's id. status: type: string enum: - queued - running - finished - failed - canceled title: Status description: >- `queued` (waiting to start), `running`, `finished`, `failed` (stopped early; unused lookups were given back) or `canceled`. country: type: string title: Country description: The country the estimates are for. Always `US` today. item_count: type: integer title: Item Count description: >- How many keywords are on the list, after repeats and blanks are dropped. counts: $ref: '#/components/schemas/KeywordBulkCounts' created_at: type: string format: date-time title: Created At description: When the list was started. started_at: anyOf: - type: string format: date-time - type: 'null' title: Started At description: When it began running. Null while it's queued. finished_at: anyOf: - type: string format: date-time - type: 'null' title: Finished At description: When it ended. Null while it's queued or running. type: object required: - id - status - country - item_count - counts - created_at - started_at - finished_at title: KeywordBulkJob description: >- A keyword list: its status and progress, without the per-keyword results. KeywordBulkActiveResponse: properties: detail: $ref: '#/components/schemas/KeywordBulkActiveError' type: object required: - detail title: KeywordBulkActiveResponse description: >- The 409 body as sent: the running list, inside the API's usual ``detail`` envelope. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError KeywordBulkCounts: properties: pending: type: integer title: Pending description: Waiting to run. default: 0 running: type: integer title: Running description: Being estimated now. default: 0 done: type: integer title: Done description: Finished, with results. default: 0 failed: type: integer title: Failed description: Couldn't be estimated. Their weekly lookups were given back. default: 0 skipped_weekly_limit: type: integer title: Skipped Weekly Limit description: 'Not run: the brand''s weekly lookups ran out.' default: 0 canceled: type: integer title: Canceled description: 'Not run: the list was canceled or stopped first.' default: 0 type: object title: KeywordBulkCounts description: How many of the list's keywords are in each status. KeywordBulkActiveError: properties: error: type: string const: bulk_job_active title: Error default: bulk_job_active job_id: type: integer title: Job Id description: The running list's id, to poll or cancel. message: type: string title: Message type: object required: - job_id - message title: KeywordBulkActiveError description: The brand already has a keyword list running. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: HTTPBearer: type: http scheme: bearer ```` ## Related topics - [Scrunch MCP Feature Reference and Example Prompts](https://developers.scrunch.com/mcp/tools.md) - [Keyword Volume API: Estimate a keyword list](https://developers.scrunch.com/api-reference/keyword-volume/overview.md) - [Cancel Keyword List](https://developers.scrunch.com/api-reference/keyword-volume/cancel-keyword-list.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.