Skip to navigation
Models and searchAnalyze and segment videosBatch analysis

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.

When to use this method:

  • Run the same 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.
  • An item whose analysis window exceeds 2 hours fails on its own. The error code is video_duration_too_long. The rest of the batch is still submitted.

Limits:

  • Up to 1,000 requests per batch.
  • Up to 2,000 total content hours per batch.
  • Up to 5 active batches per account.
  • The duration limits of the POST method of the /analyze/tasks endpoint apply to each item.

Authentication

x-api-keystring

Your API key.

Note

You can find your API key on the API Keys page.

Request

This endpoint expects an object.
model_nameenumRequired
The video understanding model to use for every item in this batch.
Allowed values:
analysis_modeenumRequired

The analysis mode for every item in this batch.

  • general: Generate text from each video based on the prompt (the prompt field of the item 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.

Allowed values:
requestslist of objectsRequired
The analysis requests in the batch. Provide 1 to 1,000 requests, with a combined video duration of up to 2,000 hours.
defaultsobjectOptional

Default values applied to every item that does not override them. Every field is optional. Items in the requests array override these values. To override the prompt or response_format field, provide the full object on the item. You cannot change only some of its nested fields.

Response headers

LocationstringOptional

Response

The platform has created the batch and queued an analysis task for each request.
batch_idstring
The unique identifier of the batch.
statusenum

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

total_itemsinteger
The number of items submitted in the batch.
created_atstringformat: "date-time"
The date and time, in the RFC 3339 format, when the batch was created.
expires_atstringformat: "date-time"

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.

itemslist of objects
One entry per submitted item. Each entry pairs the unique task identifier generated by the platform with the custom identifier you provided when you created the batch.

Errors

400
Bad Request Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error
503
Service Unavailable Error
504
Gateway Timeout Error