> ## 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. # Get Keyword List > A keyword list's status and every keyword on it, with each finished keyword's weekly volume, Demand Score and Commercial Intent score. Poll it while the list is `queued` or `running`; every 30 seconds is plenty. Results stay readable after the list ends. ## OpenAPI ````yaml /api-reference/openapi.json get /{brand_id}/keyword-volume/lists/{list_id} 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/{list_id}: get: tags: - keyword-volume summary: Get Keyword List description: >- A keyword list's status and every keyword on it, with each finished keyword's weekly volume, Demand Score and Commercial Intent score. Poll it while the list is `queued` or `running`; every 30 seconds is plenty. Results stay readable after the list ends. operationId: getKeywordList parameters: - name: brand_id in: path required: true schema: type: integer title: Brand Id - name: list_id in: path required: true schema: type: integer description: The keyword list's id, from Start Keyword List title: List Id description: The keyword list's id, from Start Keyword List responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/KeywordBulkJobDetail' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: - query components: schemas: KeywordBulkJobDetail: 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. items: items: $ref: '#/components/schemas/KeywordBulkItem' type: array title: Items type: object required: - id - status - country - item_count - counts - created_at - started_at - finished_at - items title: KeywordBulkJobDetail description: A keyword list with every keyword on it, in list order. 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. KeywordBulkItem: properties: position: type: integer title: Position description: The keyword's place on the list, from 0. keyword: type: string title: Keyword description: The keyword as estimated, after trimming. status: type: string enum: - pending - running - done - failed - skipped_weekly_limit - canceled title: Status description: >- `pending`, `running`, `done`, `failed`, `skipped_weekly_limit` (the brand's weekly lookups ran out) or `canceled`. result: anyOf: - $ref: '#/components/schemas/KeywordBulkResult' - type: 'null' description: The keyword's numbers once `status` is `done`; null before. type: object required: - position - keyword - status title: KeywordBulkItem description: One keyword on a list, with its numbers once done. 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 KeywordBulkResult: properties: weekly_estimate: anyOf: - type: number - type: 'null' title: Weekly Estimate description: Estimated weekly US AI prompt volume for the keyword. estimated: type: boolean title: Estimated description: >- True when there was too little direct evidence for a reading, so `weekly_estimate` is modeled. default: false demand_score: anyOf: - type: integer maximum: 100 minimum: 0 - type: 'null' title: Demand Score description: >- 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: anyOf: - type: string - type: 'null' title: Demand Label description: >- The Demand Score's band: `No demand`, `Very Low`, `Low`, `Medium`, `High` or `Very High`. commercial_intent_score: anyOf: - type: integer maximum: 100 minimum: 0 - type: 'null' title: Commercial Intent Score description: >- How buying-oriented the prompts for this keyword are, from 0 to 100. Higher means more commercial than AI prompts in general. Null when there wasn't enough to score. degraded: type: boolean title: Degraded description: >- True when part of the estimate couldn't run, so the numbers may read low. Estimate the keyword again later. default: false type: object required: - weekly_estimate title: KeywordBulkResult description: >- One keyword's estimate: its weekly volume, Demand Score and Commercial Intent score, the same numbers the Keyword Volume page shows. ``weekly_estimate``, ``demand_score`` and ``demand_label`` are null together when the keyword couldn't be measured. 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) - [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.