Sign in

v3

latestOpenAPI 3.1.02026-07-3197486526.1 KB
analyzeAsync > batches

Create a batch

Use this method to submit many video analysis requests in a single call. Each request creates an analysis task. The response contains one batch identifier and one task identifier per request. Use the batch identifier to check progress and retrieve results.

<Note title="Model requirement"> You must use Pegasus 1.5 for batch analysis. Set the `model_name` parameter to `pegasus1.5`. </Note>

When to use this method:

  • Run the same model and analysis settings across many videos.
  • Track a single batch instead of many individual analysis tasks.

Do not use this method for:

  • Single videos that require immediate results. Use the POST method of the /analyze endpoint instead.
  • Background processing of a single video. Use the POST method of the /analyze/tasks endpoint instead.

Retention and retry:

  • Batches expire 24 hours after creation. You can retrieve results for 30 days after creation.
  • If processing does not finish for some items in time, resubmit them in a new batch.

Limits:

  • Up to 1,000 requests per batch.
  • Up to 2,000 total content hours per batch.
  • Up to 5 active batches per account.
post/analyze/batches

Headers

x-api-keystring required

Your API key.

<Note title="Note"> You can find your API key on the <a href="https://playground.twelvelabs.io/dashboard/api-keys" target="_blank">API Keys</a> page. </Note>

Request body

model_name'pegasus1.5' required

The video understanding model to use for every item in this batch. Batch analysis requires Pegasus 1.5.

analysis_mode'general' | 'time_based_metadata' required

The analysis approach for every item in this batch.

  • general: Generate text from each video based on the prompt (the item's prompt field if set, otherwise defaults.prompt). Supports structured JSON output by using json_schema in the response_format.type field.
  • time_based_metadata: Extract timestamped metadata by using segment_definitions in the response_format.type field.

Batches with mixed modes are not supported.

Response

The platform has created the batch and queued an analysis task for each request.

batch_idstring required

The unique identifier of the batch.

status'pending' | 'processing' | 'canceling' | 'canceled' | 'completed' | 'expired' required

The status of a batch. For the meaning of each value, see the Batch statuses section on the The batch object page.

total_itemsinteger required

The number of items submitted in the batch.

created_atstring date-time required

The date and time, in the RFC 3339 format, when the batch was created.

expires_atstring date-time required

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.