Sign in

v3

latestOpenAPI 3.1.02026-07-3197486526.1 KB
analyzeAsync > batches

Cancel a batch

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.

post/analyze/batches/{batch_id}/cancel

Path parameters

batch_idstring required

The unique identifier of the batch.

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>

Response

The platform accepted the cancellation request. Items already in the processing status continue until processing finishes. The batch status is canceling until every item reaches ready, failed, or canceled, then becomes canceled. The response shows the batch state at the time of the request. To confirm the batch is fully canceled, use the GET method of the /analyze/batches/{batch_id} endpoint.

batch_idstring required

The unique identifier of the batch. Use this value to retrieve the batch status or results.

analysis_mode'general' | 'time_based_metadata' required

The analysis mode applied to every item in this batch.

model_namestring required

The model used for every item in this 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.

completed_atstring date-time

The date and time, in the RFC 3339 format, when the batch status became completed. Present only when the status is completed.

canceled_atstring date-time

The date and time, in the RFC 3339 format, when the batch status became canceled. Present only when the status is canceled.

expired_atstring date-time

The date and time, in the RFC 3339 format, when the batch status became expired. Present only when the status is expired.

queued_itemsinteger required

The number of items in the queued status.

processing_itemsinteger required

The number of items in the processing status.

ready_itemsinteger required

The number of items that completed successfully.

failed_itemsinteger required

The number of items that failed.

canceled_itemsinteger required

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.