The AnalyzeAsyncClient.BatchesClient class provides methods to submit up to 1,000 video analysis requests in a single call, monitor batch progress, retrieve per-item results, and cancel or delete batches.

When to use this class:

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

Do not use this class for:

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

Working with batches involves the following steps:

1. Create the batch using the create method. The platform returns a batch identifier and one analysis task identifier per request.
2. Monitor the batch using the retrieve method. Wait until the status reaches completed, canceled, or expired.
3. Retrieve the per-item results using the results method.
4. (Optional) Cancel the batch using the cancel method while the status is pending or processing.
5. (Optional) Delete the batch using the delete method after the status reaches completed, canceled, or expired.

For schema details and status definitions, see the The batch object page.

Methods

Create a batch

Description: 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.

Limits:

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

Retention: 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.

Function signature and example:

1
def create(
2
    self,
3
    *,
4
    model_name: CreateAnalyzeBatchRequestModelName,
5
    analysis_mode: CreateAnalyzeBatchRequestAnalysisMode,
6
    requests: typing.Sequence[BatchItemRequest],
7
    defaults: typing.Optional[BatchDefaults] = OMIT,
8
    request_options: typing.Optional[RequestOptions] = None,
9
) -> CreateAnalyzeBatchResponse

Parameters:

BatchItemRequest

The BatchItemRequest class describes a single analysis request inside a batch. Identify the asset in the video field. Every other field is optional and overrides the matching field in the defaults object.

BatchVideoContext

The BatchVideoContext class identifies the asset to analyze. Batch analysis accepts only assets. URLs and base64-encoded video data are not supported.

BatchDefaults

The BatchDefaults class defines 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.

BatchPrompt

The BatchPrompt class defines a structured prompt with <@name> placeholders for referencing images. Not supported when the analysis_mode field is "time_based_metadata".

Return value: Returns a CreateAnalyzeBatchResponse object.

The CreateAnalyzeBatchResponse class contains the following properties:

CreatedBatchItem

The CreatedBatchItem class contains the following properties:

API Reference: Create a batch

List batches

Description: This method returns a list of the batch objects in your account. The platform returns your batches sorted by creation date, with the newest batch first.

Function signature and example:

1
def list(
2
    self,
3
    *,
4
    page: typing.Optional[int] = None,
5
    page_limit: typing.Optional[int] = None,
6
    status: typing.Optional[typing.Union[BatchStatus, typing.Sequence[BatchStatus]]] = None,
7
    analysis_mode: typing.Optional[
8
        typing.Union[BatchesListRequestAnalysisModeItem, typing.Sequence[BatchesListRequestAnalysisModeItem]]
9
    ] = None,
10
    request_options: typing.Optional[RequestOptions] = None,
11
) -> SyncPager[AnalyzeBatchStatusResponse]

Parameters:

Return value: Returns a SyncPager[AnalyzeBatchStatusResponse] object. Iterate over it directly to receive batches across pages, or call iter_pages() to receive each page as a list. For the per-batch object schema, see Retrieve batch status below.

API Reference: List batches

Retrieve batch status

Description: Use this method to monitor a batch. The response includes the current batch status and counts for queued, processing, ready, failed, and canceled items.

Poll this method until the batch reaches the completed, canceled, or expired status. To retrieve the results, call the results method.

Function signature and example:

1
def retrieve(
2
    self,
3
    batch_id: str,
4
    *,
5
    request_options: typing.Optional[RequestOptions] = None,
6
) -> AnalyzeBatchStatusResponse

Parameters:

Return value: Returns an AnalyzeBatchStatusResponse object.

The AnalyzeBatchStatusResponse class contains the following properties:

API Reference: Retrieve batch status

Retrieve batch results

Description: Use this method to retrieve the results for each item in a batch. You can call it while the batch has the pending or processing status.

Each result entry has a status. For details on each status, see the Item statuses section on the The batch object page.

Each result entry includes a task identifier in the task_id field. Use this value with analyze_async.tasks.retrieve if you need the full analysis task response.

You can retrieve results for 30 days after batch creation.

The method streams the response. Iterate over the returned generator to receive one BatchResultItem per batch item.

Function signature and example:

1
def results(
2
    self,
3
    batch_id: str,
4
    *,
5
    request_options: typing.Optional[RequestOptions] = None,
6
) -> typing.Iterator[BatchResultItem]

Parameters:

Yields: An iterator of BatchResultItem objects. Each entry corresponds to one batch item.

The BatchResultItem class contains the following properties:

BatchItemError

The BatchItemError class contains the following properties:

API Reference: Retrieve batch results

Cancel a batch

Description: Use this method to request cancellation for a batch with the pending or processing status.

When you invoke this method, the platform performs the following steps:

• Cancels the items in the queued status.
• Finishes the analysis for the items in the processing status.

The batch status changes to canceling immediately, and to canceled after every item reaches ready, failed, or canceled. You are not billed for canceled or failed items.

Function signature and example:

1
def cancel(
2
    self,
3
    batch_id: str,
4
    *,
5
    request_options: typing.Optional[RequestOptions] = None,
6
) -> AnalyzeBatchStatusResponse

Parameters:

Return value: Returns an AnalyzeBatchStatusResponse object that reflects the batch state at the time of the request. The batch status is canceling until every item reaches ready, failed, or canceled, then becomes canceled. To confirm the batch is fully canceled, call the retrieve method. For the return type properties, see Retrieve batch status.

API Reference: Cancel a batch

Delete a batch

Description: Use this method to delete a batch and all the tasks associated with it. You can only delete batches with status completed, canceled, or expired.

Deleting a batch does not affect billing. You are billed for every completed analysis regardless of whether you delete the batch afterward.

To stop a batch with the pending or processing status, use the cancel method.

Batches are deleted 30 days after creation.

Function signature and example:

1
def delete(
2
    self,
3
    batch_id: str,
4
    *,
5
    request_options: typing.Optional[RequestOptions] = None,
6
) -> None

Parameters:

Return value: Returns None. If successful, the platform returns a 204 No Content response.

API Reference: Delete a batch