> This page is for version v1.3 (default).
> For other versions, use one of these documentation indexes:
> - v1.3 (default): https://docs.twelvelabs.io/v1.3/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.twelvelabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server.

# Batch analysis

> Analyze multiple videos in a single API call.

Use the batch analysis endpoints to submit multiple video analysis requests in a single API call. The response contains a batch identifier. Use it to check progress and retrieve results for every request.

Upload each video as an asset before creating a batch. See the [Upload content](/v1.3/api-reference/upload-content) page for the available methods. Provide the asset identifiers when creating the batch.

For schema details and status definitions, see [The batch object](/v1.3/api-reference/analyze-videos/batch-analysis/the-batch-object) page.

For the limits per batch (request count, content hours, concurrent batches), see the [Create a batch](/v1.3/api-reference/analyze-videos/batch-analysis/create-batch) page.

# Workflow

**Create the batch**: Invoke the [`POST`](/v1.3/api-reference/analyze-videos/batch-analysis/create-batch) method of the `/analyze/batches` endpoint. Set the `model_name` parameter to `pegasus1.5`. Include one analysis request per asset. To map each result back to a record in your system, set the `custom_id` field on each item. Store the `batch_id` value from the response; you'll use it to check progress and retrieve results. Each request also returns a task identifier in the `task_id` field; save these if you need to retrieve details about individual analyses via the [`GET`](/v1.3/api-reference/analyze-videos/retrieve-analysis-task-status-results) method of the `/analyze/tasks/{task_id}` endpoint.

**Check the batch status**: Invoke the [`GET`](/v1.3/api-reference/analyze-videos/batch-analysis/retrieve-batch-status) method of the `/analyze/batches/{batch_id}` endpoint until the status is `completed`, `canceled`, or `expired`.

**Retrieve the results**: Invoke the [`GET`](/v1.3/api-reference/analyze-videos/batch-analysis/retrieve-batch-results) method of the `/analyze/batches/{batch_id}/results` endpoint. The response uses JSON Lines (`application/jsonl`), with one result per line. Each result includes a task identifier in the `task_id` field; use it with the [`GET`](/v1.3/api-reference/analyze-videos/retrieve-analysis-task-status-results) method of the `/analyze/tasks/{task_id}` endpoint to retrieve the full task response for a single item.

*(Optional)* **Cancel the batch**: Invoke the [`POST`](/v1.3/api-reference/analyze-videos/batch-analysis/cancel-batch) method of the `/analyze/batches/{batch_id}/cancel` endpoint while the status is `pending` or `processing`.

*(Optional)* **Delete the batch**: Invoke the [`DELETE`](/v1.3/api-reference/analyze-videos/batch-analysis/delete-batch) method of the `/analyze/batches/{batch_id}` endpoint after the status reaches `completed`, `canceled`, or `expired`.

You are billed for every completed analysis. Canceled or failed items are not billed. Deleting a batch does not affect billing for completed items.