> This page is for version v1.3 (default).
> For other versions, use one of these documentation indexes:
> - v1.3 (default): https://beta.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://beta.docs.twelvelabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://beta.docs.twelvelabs.io/_mcp/server.

# The batch object

> Batch object schema for batch analysis.

A batch object represents a group of video analysis requests submitted in one API call. The [List batches](/v1.3/api-reference/analyze-videos/batch-analysis/list-batches), [Retrieve batch status](/v1.3/api-reference/analyze-videos/batch-analysis/retrieve-batch-status), and [Cancel a batch](/v1.3/api-reference/analyze-videos/batch-analysis/cancel-batch) endpoints all return batch objects.

# Request, item, and task

Inside a batch, the same single-video analysis unit has three names depending on lifecycle stage:

* **Request**: What you submit. The body of the [Create a batch](/v1.3/api-reference/analyze-videos/batch-analysis/create-batch) endpoint takes a `requests[]` array; each element is a single analysis request.
* **Item**: How the batch tracks progress. The counter fields (`total_items`, `queued_items`, `processing_items`, `ready_items`, `failed_items`, `canceled_items`) count items by state.
* **Task**: How you address an individual analysis. Each request becomes an analysis task with its own `task_id`, retrievable through the [Retrieve analysis task status and results](/v1.3/api-reference/analyze-videos/retrieve-analysis-task-status-results) endpoint.

# Batch fields

A batch object has the following fields:

* `batch_id`: The unique identifier of the batch. Use this value to retrieve status, retrieve results, cancel the batch, or delete the batch.
* `analysis_mode`: The analysis mode applied to every item in the batch.
* `model_name`: The model used for every item in the batch.
* `status`: The status of the batch. See the [Batch statuses](#batch-statuses) section for details.
* `total_items`: The number of items submitted in the batch.
* `queued_items`: The number of items waiting to be processed.
* `processing_items`: The number of items being processed.
* `ready_items`: The number of items that completed successfully.
* `failed_items`: The number of items that failed.
* `canceled_items`: The number of items that were canceled, either because the batch was canceled while the item was in the `queued` status, or because the batch expired before the item finished processing.
* `created_at`: The date and time, in the RFC 3339 format, when the batch was created.
* `expires_at`: The date and time, in the RFC 3339 format, when the batch expires (the `created_at` field value plus 24 hours). Unfinished items at expiration are canceled. Items that finished before then remain retrievable for 30 days after creation, when the batch and its results are deleted.
* `webhooks`: The delivery status of each webhook endpoint for the batch completion notification. Present only after the platform sends the webhook notifications. To register webhooks, see the [Webhooks](/v1.3/docs/advanced/webhooks) page.
* `completed_at`: The date and time, in the RFC 3339 format, when the batch status became `completed`. Present only when the status is `completed`.
* `canceled_at`: The date and time, in the RFC 3339 format, when the batch status became `canceled`. Present only when the status is `canceled`.
* `expired_at`: The date and time, in the RFC 3339 format, when the batch status became `expired`. Present only when the status is `expired`.

# Batch statuses

The `status` field of a batch object has one of the following values. The status reflects the batch as a whole, not individual items. See the [Item statuses](#item-statuses) section for per-item state.

* `pending`: The batch was submitted, but processing has not started for any item.
* `processing`: At least one item is being processed.
* `canceling`: A cancel request is in progress.
* `canceled`: The platform has finished canceling the batch.
* `completed`: Processing has finished for every item, regardless of per-item outcome.
* `expired`: The 24-hour deadline elapsed before processing finished for every item.

A batch never has the `failed` status. The `completed` status means that processing has finished for every item, not that every analysis succeeded. To monitor success, check the `ready_items`, `failed_items`, and `canceled_items` fields.

# Item statuses

Each item in a batch has its own status, separate from the batch status. The [Retrieve batch results](/v1.3/api-reference/analyze-videos/batch-analysis/retrieve-batch-results) endpoint returns one result entry per item, each with one of the following statuses:

* `queued`: The item is waiting for analysis to start.
* `processing`: Analysis has started for the item.
* `ready`: Analysis succeeded. The result entry includes a `data` field with the result.
* `failed`: Analysis failed. The result entry includes an `error` field describing the failure.
* `canceled`: The item was canceled, either because the batch was canceled while the item was in the `queued` status, or because the batch expired before the item finished processing.