> This page is for version v1.3 (default). > For other versions, use one of these documentation indexes: > - v1.3 (default): https://beta.docs.twelvelabs.io/v1.3/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://beta.docs.twelvelabs.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://beta.docs.twelvelabs.io/_mcp/server. 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 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`](/v1.3/sdk-reference/python/analyze-videos/sync-analysis#sync-analysis) method instead. * Background processing of a single video. Use the [`analyze_async.tasks.create`](/v1.3/sdk-reference/python/analyze-videos/async-analysis#create-an-async-analysis-task) method instead. Working with batches involves the following steps: 1. Create the batch using the [`create`](#create-a-batch) method. The platform returns a batch identifier and one analysis task identifier per request. 2. Monitor the batch using the [`retrieve`](#retrieve-batch-status) method. Wait until the status reaches `completed`, `canceled`, or `expired`. 3. Retrieve the per-item results using the [`results`](#retrieve-batch-results) method. 4. *(Optional)* Cancel the batch using the [`cancel`](#cancel-a-batch) method while the status is `pending` or `processing`. 5. *(Optional)* Delete the batch using the [`delete`](#delete-a-batch) method after the status reaches `completed`, `canceled`, or `expired`. For schema details and status definitions, see the [The batch object](/v1.3/api-reference/analyze-videos/batch-analysis/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. * The duration limits of the [`POST`](/v1.3/api-reference/analyze-videos/create-async-analysis-task) method of the `/analyze/tasks` endpoint apply to each item. **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. 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. **Function signature and example**: **`Function signature`** ```python Function signature def create( self, *, model_name: CreateAnalyzeBatchRequestModelName, analysis_mode: CreateAnalyzeBatchRequestAnalysisMode, requests: typing.Sequence[BatchItemRequest], defaults: typing.Optional[BatchDefaults] = OMIT, request_options: typing.Optional[RequestOptions] = None, ) -> CreateAnalyzeBatchResponse ``` **`General analysis example`** ```python General analysis example from twelvelabs import ( BatchDefaults, BatchItemRequest, BatchPrompt, BatchVideoContext, TwelveLabs, ) client = TwelveLabs(api_key="") response = client.analyze_async.batches.create( model_name="pegasus1.5", analysis_mode="general", defaults=BatchDefaults( prompt=BatchPrompt( input_text="Generate a 3-sentence executive summary of this video.", ), temperature=0.2, max_tokens=4096, ), requests=[ BatchItemRequest( video=BatchVideoContext(type="asset_id", asset_id=""), custom_id="summary-001", ), BatchItemRequest( video=BatchVideoContext(type="asset_id", asset_id=""), custom_id="summary-002", ), BatchItemRequest( video=BatchVideoContext(type="asset_id", asset_id=""), custom_id="action-003", prompt=BatchPrompt(input_text="List all action items discussed."), ), ], ) print(f"Batch ID: {response.batch_id}") print(f"Status: {response.status}") for item in response.items: print(f" task_id={item.task_id} custom_id={item.custom_id}") ``` **Parameters**: | Name | Type | Required | Description | | ----------------- | --------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model_name` | `CreateAnalyzeBatchRequestModelName` | Yes | The video understanding model to use for every item in this batch. Value: `"pegasus1.5"`. | | `analysis_mode` | `CreateAnalyzeBatchRequestAnalysisMode` | Yes | The analysis mode for every item in this batch. Values: - `"general"`: Generate text from each video based on the prompt (the item's `prompt` field 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. | | `requests` | `typing.Sequence[BatchItemRequest]` | Yes | The analysis requests in the batch. Provide 1 to 1,000 requests, with a combined video duration of up to 2,000 hours. See [BatchItemRequest](#batchitemrequest). | | `defaults` | `typing.Optional[BatchDefaults]` | No | Default values applied to every item that does not override them. See [BatchDefaults](#batchdefaults). | | `request_options` | `typing.Optional[RequestOptions]` | No | Request-specific configuration. | ### 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. | Name | Type | Required | Description | | ---------------------- | ------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `video` | `BatchVideoContext` | Yes | The asset to analyze. See [BatchVideoContext](#batchvideocontext). | | `custom_id` | `Optional[str]` | No | An optional identifier you set per item when you create the batch. Use this field to map batch results back to records in your system, for example, to correlate each result with the source video in your database. The platform stores this value unchanged and returns it in batch responses and task responses. **Format**: 1 to 64 characters. Alphanumeric, hyphens (`-`), and underscores (`_`) only. The value must be unique within a batch. | | `prompt` | `Optional[BatchPrompt]` | No | Override the `defaults.prompt` value for this item. See [BatchPrompt](#batchprompt). | | `response_format` | `Optional[AsyncResponseFormat]` | No | Override the `defaults.response_format` value for this item. For the type definition, see the [Create an async analysis task](/v1.3/sdk-reference/python/analyze-videos/async-analysis#create-an-async-analysis-task) method. | | `temperature` | `Optional[float]` | No | Override the `defaults.temperature` value for this item. | | `max_tokens` | `Optional[int]` | No | Override the `defaults.max_tokens` value for this item. | | `min_segment_duration` | `Optional[float]` | No | Override the `defaults.min_segment_duration` value for this item. | | `max_segment_duration` | `Optional[float]` | No | Override the `defaults.max_segment_duration` value for this item. | | `start_time` | `Optional[float]` | No | Override the `defaults.start_time` value for this item. | | `end_time` | `Optional[float]` | No | Override the `defaults.end_time` value for this item. | ### BatchVideoContext The `BatchVideoContext` class identifies the asset to analyze. Batch analysis accepts only assets. URLs and base64-encoded video data are not supported. | Name | Type | Required | Description | | ---------- | ----- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `type` | `str` | Yes | Set this field to `"asset_id"`. | | `asset_id` | `str` | Yes | The unique identifier of an asset from a [direct](/v1.3/sdk-reference/python/upload-content/direct-uploads) or [multipart](/v1.3/sdk-reference/python/upload-content/multipart-uploads) upload. The asset status must be `ready`. Use [`assets.retrieve`](/v1.3/sdk-reference/python/manage-assets#retrieve-an-asset) to check the status. | ### 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. | Name | Type | Required | Description | | ---------------------- | ------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `prompt` | `Optional[BatchPrompt]` | No | The default prompt applied to every item. See [BatchPrompt](#batchprompt). | | `response_format` | `Optional[AsyncResponseFormat]` | No | The default response format applied to every item. For the type definition, see the [Create an async analysis task](/v1.3/sdk-reference/python/analyze-videos/async-analysis#create-an-async-analysis-task) method. | | `temperature` | `Optional[float]` | No | Controls the randomness of the text output. **Default:** `0.2`. **Min:** `0`. **Max:** `1`. | | `max_tokens` | `Optional[int]` | No | The maximum number of tokens to generate per item. For general mode: **Min:** `512`, **Max:** `98,304`. For `time_based_metadata` mode: **Min:** `2,048`, **Max:** `98,304`. | | `min_segment_duration` | `Optional[float]` | No | Minimum duration for each extracted segment, in seconds. Applies only when the `analysis_mode` field is `"time_based_metadata"`. **Min:** `2`. | | `max_segment_duration` | `Optional[float]` | No | Maximum duration for each extracted segment, in seconds. Must be greater than or equal to the `min_segment_duration` field. Applies only when the `analysis_mode` field is `"time_based_metadata"`. **Min:** `2`. | | `start_time` | `Optional[float]` | No | Start of the analysis window, in seconds, applied to every item. Use with `end_time` to analyze only a portion of each video. If omitted, defaults to `0`. Must be less than `end_time`. The window (`end_time - start_time`) must be at least 1 second and at most 2 hours for each item. Each video may be up to 4 hours as long as the window stays within that limit. Mutually exclusive with `response_format.segment_definitions[].time_ranges`. | | `end_time` | `Optional[float]` | No | End of the analysis window, in seconds, applied to every item. Use with `start_time` to analyze only a portion of each video. If omitted, defaults to the video duration. Must be greater than `start_time`. The window (`end_time - start_time`) must be at least 1 second and at most 2 hours for each item. Each video may be up to 4 hours as long as the window stays within that limit. Mutually exclusive with `response_format.segment_definitions[].time_ranges`. | ### 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"`. | Name | Type | Required | Description | | --------------- | -------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input_text` | `str` | Yes | The text of the prompt. Use `<@name>` placeholders to reference images declared in `media_sources`. This text counts toward the [context window](/v1.3/docs/concepts/models/pegasus/pegasus-1-6#context-window). | | `media_sources` | `Optional[List[SmeMediaSource]]` | No | Reference images for the `<@name>` placeholders in the prompt. Maximum 4 sources. For the type definition, see [SmeMediaSource](/v1.3/sdk-reference/python/analyze-videos/async-analysis#smemediasource) on the **Async analysis** page. | **Return value**: Returns a `CreateAnalyzeBatchResponse` object. The `CreateAnalyzeBatchResponse` class contains the following properties: | Name | Type | Description | | ------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_id` | `str` | The unique identifier of the batch. | | `status` | `BatchStatus` | The initial status of the batch. Values: `pending`, `processing`, `canceling`, `canceled`, `completed`, `expired`. | | `total_items` | `int` | The number of items submitted in the batch. | | `created_at` | `datetime` | The date and time, in the RFC 3339 format, when the batch was created. | | `expires_at` | `datetime` | The date and time, in the RFC 3339 format, when the batch expires. Unfinished items at expiration are canceled. | | `items` | `List[CreatedBatchItem]` | One entry per submitted item. Each entry pairs the unique task identifier generated by the platform with the custom identifier you provided. See [CreatedBatchItem](#createdbatchitem). | ### CreatedBatchItem The `CreatedBatchItem` class contains the following properties: | Name | Type | Description | | ----------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `task_id` | `str` | The unique task identifier generated by the platform for this item. Use this value with [`analyze_async.tasks.retrieve`](/v1.3/sdk-reference/python/analyze-videos/async-analysis#retrieve-task-status-and-results) to retrieve the task's status and results. | | `custom_id` | `str` | The custom identifier you provided when you created the batch. If you did not provide one, this field is `null`. | **API Reference**: [Create a batch](/v1.3/api-reference/analyze-videos/batch-analysis/create-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**: **`Function signature`** ```python Function signature def list( self, *, page: typing.Optional[int] = None, page_limit: typing.Optional[int] = None, status: typing.Optional[typing.Union[BatchStatus, typing.Sequence[BatchStatus]]] = None, analysis_mode: typing.Optional[ typing.Union[BatchesListRequestAnalysisModeItem, typing.Sequence[BatchesListRequestAnalysisModeItem]] ] = None, request_options: typing.Optional[RequestOptions] = None, ) -> SyncPager[AnalyzeBatchStatusResponse] ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs client = TwelveLabs(api_key="") response = client.analyze_async.batches.list( page=1, page_limit=10, ) for batch in response: print(f" batch_id={batch.batch_id} status={batch.status} total_items={batch.total_items}") ``` **Parameters**: | Name | Type | Required | Description | | ----------------- | --------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page` | `Optional[int]` | No | A number that identifies the page to retrieve. **Default**: `1`. | | `page_limit` | `Optional[int]` | No | The number of items to return on each page. **Default**: `10`. **Max**: `50`. | | `status` | `Optional[Union[BatchStatus, Sequence[BatchStatus]]]` | No | Filter batches by status. Provide one or more values to include batches matching any of them. If omitted, the response includes batches in all statuses. | | `analysis_mode` | `Optional[Union[BatchesListRequestAnalysisModeItem, Sequence[BatchesListRequestAnalysisModeItem]]]` | No | Filter batches by analysis mode. Provide one or more values to include batches matching any of them. Values: `"general"`, `"time_based_metadata"`. If omitted, the response includes batches in all analysis modes. | | `request_options` | `Optional[RequestOptions]` | No | Request-specific configuration. | **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](#retrieve-batch-status) below. **API Reference**: [List batches](/v1.3/api-reference/analyze-videos/batch-analysis/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`](#retrieve-batch-results) method. > **Note** > > Do not treat the `completed` status as a success signal. It means processing has finished for every item, not that every analysis succeeded. To see how many items succeeded, failed, or were canceled, check the `ready_items`, `failed_items`, and `canceled_items` fields. A batch never has the `failed` status. **Function signature and example**: **`Function signature`** ```python Function signature def retrieve( self, batch_id: str, *, request_options: typing.Optional[RequestOptions] = None, ) -> AnalyzeBatchStatusResponse ``` **`Poll for batch completion`** ```python Poll for batch completion from twelvelabs import TwelveLabs import time client = TwelveLabs(api_key="") while True: batch = client.analyze_async.batches.retrieve(batch_id="") print( f"Status: {batch.status} " f"(ready={batch.ready_items}, failed={batch.failed_items}, canceled={batch.canceled_items})" ) if batch.status in ("completed", "canceled", "expired"): break time.sleep(10) ``` **Parameters**: | Name | Type | Required | Description | | ----------------- | -------------------------- | -------- | ----------------------------------- | | `batch_id` | `str` | Yes | The unique identifier of the batch. | | `request_options` | `Optional[RequestOptions]` | No | Request-specific configuration. | **Return value**: Returns an `AnalyzeBatchStatusResponse` object. The `AnalyzeBatchStatusResponse` class contains the following properties: | Name | Type | Description | | ------------------ | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_id` | `str` | The unique identifier of the batch. | | `analysis_mode` | `str` | The analysis mode applied to every item in this batch. Values: `"general"`, `"time_based_metadata"`. | | `model_name` | `str` | The model used for every item in this batch. | | `status` | `BatchStatus` | The current batch status. Values: `pending`, `processing`, `canceling`, `canceled`, `completed`, `expired`. | | `total_items` | `int` | The number of items submitted in the batch. | | `queued_items` | `int` | The number of items in the `queued` status. | | `processing_items` | `int` | The number of items in the `processing` status. | | `ready_items` | `int` | The number of items that completed successfully. | | `failed_items` | `int` | The number of items that failed. | | `canceled_items` | `int` | 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` | `datetime` | The date and time, in the RFC 3339 format, when the batch was created. | | `expires_at` | `datetime` | The date and time, in the RFC 3339 format, when the batch expires. | | `completed_at` | `Optional[datetime]` | The date and time, in the RFC 3339 format, when the batch status became `completed`. Present only when the status is `completed`. | | `canceled_at` | `Optional[datetime]` | The date and time, in the RFC 3339 format, when the batch status became `canceled`. Present only when the status is `canceled`. | | `expired_at` | `Optional[datetime]` | The date and time, in the RFC 3339 format, when the batch status became `expired`. Present only when the status is `expired`. | | `webhooks` | `Optional[List[AnalyzeTaskWebhookInfo]]` | 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](/v1.3/docs/advanced/webhooks) page. | **API Reference**: [Retrieve batch status](/v1.3/api-reference/analyze-videos/batch-analysis/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](/v1.3/api-reference/analyze-videos/batch-analysis/the-batch-object#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`](/v1.3/sdk-reference/python/analyze-videos/async-analysis#retrieve-task-status-and-results) 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**: **`Function signature`** ```python Function signature def results( self, batch_id: str, *, request_options: typing.Optional[RequestOptions] = None, ) -> typing.Iterator[BatchResultItem] ``` **`Stream results`** ```python Stream results from twelvelabs import TwelveLabs client = TwelveLabs(api_key="") for entry in client.analyze_async.batches.results(batch_id=""): if entry.status == "ready": print(f"[ready] {entry.custom_id}: {entry.data.data}") elif entry.status == "failed": print(f"[failed] {entry.custom_id}: {entry.error.message}") else: print(f"[{entry.status}] {entry.custom_id}") ``` **Parameters**: | Name | Type | Required | Description | | ----------------- | -------------------------- | -------- | ----------------------------------- | | `batch_id` | `str` | Yes | The unique identifier of the batch. | | `request_options` | `Optional[RequestOptions]` | No | Request-specific configuration. | **Yields**: An iterator of `BatchResultItem` objects. Each entry corresponds to one batch item. The `BatchResultItem` class contains the following properties: | Name | Type | Description | | ----------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `task_id` | `str` | The unique task identifier generated by the platform for this item. | | `custom_id` | `str` | The custom identifier you provided when you created the batch. If you did not provide one, this field is `null`. | | `status` | `BatchItemStatus` | The current status of the result entry. Values: `queued`, `processing`, `ready`, `failed`, `canceled`. | | `data` | `Optional[AnalyzeTaskResult]` | The analysis result for an entry in the `ready` status. The analysis text is in this object's nested `data` field. The envelope uses the same schema as the `result` field on [`analyze_async.tasks.retrieve`](/v1.3/sdk-reference/python/analyze-videos/async-analysis#retrieve-task-status-and-results). | | `error` | `Optional[BatchItemError]` | Failure details for an entry in the `failed` status. See [BatchItemError](#batchitemerror). | ### BatchItemError The `BatchItemError` class contains the following properties: | Name | Type | Description | | --------- | --------------- | ------------------------------------------------------------------------------- | | `code` | `Optional[str]` | A machine-readable error code identifying the failure category. May be omitted. | | `message` | `str` | A human-readable explanation of the failure. | **API Reference**: [Retrieve batch results](/v1.3/api-reference/analyze-videos/batch-analysis/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**: **`Function signature`** ```python Function signature def cancel( self, batch_id: str, *, request_options: typing.Optional[RequestOptions] = None, ) -> AnalyzeBatchStatusResponse ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs client = TwelveLabs(api_key="") batch = client.analyze_async.batches.cancel(batch_id="") print(f"Status: {batch.status}") ``` **Parameters**: | Name | Type | Required | Description | | ----------------- | -------------------------- | -------- | ----------------------------------- | | `batch_id` | `str` | Yes | The unique identifier of the batch. | | `request_options` | `Optional[RequestOptions]` | No | Request-specific configuration. | **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`](#retrieve-batch-status) method. For the return type properties, see [Retrieve batch status](#retrieve-batch-status). **API Reference**: [Cancel a batch](/v1.3/api-reference/analyze-videos/batch-analysis/cancel-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`](#cancel-a-batch) method. Batches are deleted 30 days after creation. **Function signature and example**: **`Function signature`** ```python Function signature def delete( self, batch_id: str, *, request_options: typing.Optional[RequestOptions] = None, ) -> None ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs client = TwelveLabs(api_key="") client.analyze_async.batches.delete(batch_id="") ``` **Parameters**: | Name | Type | Required | Description | | ----------------- | -------------------------- | -------- | ----------------------------------- | | `batch_id` | `str` | Yes | The unique identifier of the batch. | | `request_options` | `Optional[RequestOptions]` | No | Request-specific configuration. | **Return value**: Returns `None`. If successful, the platform returns a `204 No Content` response. **API Reference**: [Delete a batch](/v1.3/api-reference/analyze-videos/batch-analysis/delete-batch)