The AnalyzeAsync.Batches interface 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 interface:

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

Do not use this interface for:

• Single videos that require immediate results. Use the analyze method instead.
• Background processing of a single video. Use the analyzeAsync.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
create(
2
    request: TwelvelabsApi.analyzeAsync.CreateAnalyzeBatchRequest,
3
    requestOptions?: Batches.RequestOptions
4
): core.HttpResponsePromise<TwelvelabsApi.CreateAnalyzeBatchResponse>

Parameters:

CreateAnalyzeBatchRequest

The TwelvelabsApi.analyzeAsync.CreateAnalyzeBatchRequest interface has the following properties:

BatchItemRequest

The TwelvelabsApi.BatchItemRequest interface 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 TwelvelabsApi.BatchVideoContext interface identifies the asset to analyze. Batch analysis accepts only assets. URLs and base64-encoded video data are not supported.

BatchDefaults

The TwelvelabsApi.BatchDefaults interface 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 responseFormat field, provide the full object on the item. You cannot change only some of its nested fields.

BatchPrompt

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

Return value: Returns an HttpResponsePromise that resolves to a TwelvelabsApi.CreateAnalyzeBatchResponse object.

The TwelvelabsApi.CreateAnalyzeBatchResponse interface contains the following properties:

CreatedBatchItem

The TwelvelabsApi.CreatedBatchItem interface 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
list(
2
    request?: TwelvelabsApi.analyzeAsync.BatchesListRequest,
3
    requestOptions?: Batches.RequestOptions
4
): Promise<core.Page<TwelvelabsApi.AnalyzeBatchStatusResponse>>

Parameters:

The TwelvelabsApi.analyzeAsync.BatchesListRequest interface has the following properties:

Return value: Returns a promise that resolves to a core.Page<TwelvelabsApi.AnalyzeBatchStatusResponse> object. The page is an async iterable that yields batches across pages. 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
retrieve(
2
    batchId: string,
3
    requestOptions?: Batches.RequestOptions
4
): core.HttpResponsePromise<TwelvelabsApi.AnalyzeBatchStatusResponse>

Parameters:

Return value: Returns an HttpResponsePromise that resolves to a TwelvelabsApi.AnalyzeBatchStatusResponse object.

The TwelvelabsApi.AnalyzeBatchStatusResponse interface 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 taskId field. Use this value with analyzeAsync.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 resolved stream to receive one BatchResultItem per batch item.

Function signature and example:

1
results(
2
    batchId: string,
3
    requestOptions?: Batches.RequestOptions
4
): core.HttpResponsePromise<core.Stream<TwelvelabsApi.BatchResultItem>>

Parameters:

Return value: Returns an HttpResponsePromise that resolves to a core.Stream<TwelvelabsApi.BatchResultItem> object. The stream is an async iterable that yields one BatchResultItem per batch item.

The TwelvelabsApi.BatchResultItem interface contains the following properties:

BatchItemError

The TwelvelabsApi.BatchItemError interface 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
cancel(
2
    batchId: string,
3
    requestOptions?: Batches.RequestOptions
4
): core.HttpResponsePromise<TwelvelabsApi.AnalyzeBatchStatusResponse>

Parameters:

Return value: Returns an HttpResponsePromise that resolves to a TwelvelabsApi.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
delete(
2
    batchId: string,
3
    requestOptions?: Batches.RequestOptions
4
): core.HttpResponsePromise<void>

Parameters:

Return value: Returns an HttpResponsePromise that resolves to void. If successful, the platform returns a 204 No Content response.

API Reference: Delete a batch