A batch object represents a group of video analysis requests submitted in one API call. The List batches, Retrieve batch status, and Cancel a 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 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 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 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 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 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 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.