> 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. # Video indexing tasks > This method of uploading videos will be deprecated in a future version. Use direct uploads or multipart uploads followed by separate indexing. A video indexing task represents a request to upload and index a video. The `TaskClientWrapper` class provides methods to manage your video indexing tasks. # Methods ## Create a video indexing task > **Info** > > This method will be deprecated in a future version. New implementations should use [direct](/v1.3/sdk-reference/python/upload-content/direct-uploads) or [multipart](/v1.3/sdk-reference/python/upload-content/multipart-uploads) uploads followed by [separate indexing](/v1.3/sdk-reference/python/index-content#index-an-asset). **Description**: This method creates a new video indexing task that uploads and indexes a video. > **Adding videos to existing indexes** > > You can no longer add videos to an index that has only Pegasus 1.2 enabled. When you add videos to an index that has both Marengo and Pegasus 1.2 enabled, the platform indexes them with Marengo only. Your videos must meet requirements based on the models enabled for your index: * [Marengo requirements](/v1.3/docs/concepts/models/marengo/marengo-3-0#video-file-requirements). * [Pegasus requirements](/v1.3/docs/concepts/models/pegasus/pegasus-1-5#video-file-requirements). * If both models are enabled, the most restrictive limits apply. Indexes have limits on video hours and video count. For details, see the [Video hours and video count limits](/v1.3/docs/concepts/indexes#video-hours-and-video-count-limits) section. > **Note** > > This method is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. **Function signature and example**: **`Function signature`** ```python Function signature def create( self, *, index_id: str, video_file: typing.Optional[core.File] = OMIT, video_url: typing.Optional[str] = OMIT, enable_video_stream: typing.Optional[bool] = OMIT, request_options: typing.Optional[RequestOptions] = None, ) -> TasksCreateResponse: ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs task = client.tasks.create( index_id=index.id, video_url="") print(f"Created task: id={task.id}") ``` ### Parameters | Name | Type | Required | Description | | --------------------- | --------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `index_id` | `str` | Yes | The unique identifier of the index to which the video will be uploaded. | | `video_file` | `typing.` `Optional` `[core.File]` | No | The video file to upload. | | `video_url` | `typing.` `Optional[str]` | No | The publicly accessible URL of the video you want to upload. | | `enable_video_stream` | `typing.` `Optional[bool]` | No | Indicates if the platform stores the video for streaming. When set to `true`, the platform stores the video, and you can retrieve its URL by. For details, see the [Retrieve video information](/v1.3/sdk-reference/python/manage-videos#retrieve-video-information) page. | | `user_metadata:` | `typing.Optional[str]` | No | Metadata that helps you categorize your videos. You can specify a stringified list of keys and values. | | `request_options` | `typing.` `Optional` `[RequestOptions]` | No | Request-specific configuration. | ### Return value Returns a `TasksCreateResponse` instance. The `TasksCreateResponse` interface contains the following properties: | Name | Type | Description | | ---------- | -------- | ---------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of your video indexing task. | | `video_id` | `string` | The unique identifier of the video associated with your video indexing task. | ### API Reference [Create a video indexing task](/v1.3/api-reference/videos/tasks/create). ## Retrieve a video indexing task > **Info** > > This method will be removed in a future version. **Description**: This method retrieves the details of a specific video indexing task. **Function signature and example**: **`Function signature`** ```python Function signature def retrieve( self, task_id: str, *, request_options: typing.Optional[RequestOptions] = None ) -> TasksRetrieveResponse ``` **`Python example`** ```javascript Python example from twelvelabs import TwelveLabs from twelvelabs.tasks import TasksRetrieveResponse retrieved_task = client.tasks.retrieve(task_id="YOUR_VIDEO_INDEXING_TASK_ID" ) print(f"Task ID: {retrieved_task.id}") print(f"Index ID: {retrieved_task.index_id}") print(f"Video ID: {retrieved_task.video_id}") print(f"Status: {retrieved_task.status}") print("System metadata:") print(retrieved_task.system_metadata) if retrieved_task.hls: print("HLS:") print(f" Video URL: {retrieved_task.hls.video_url}") print(" Thumbnail URLs:") for url in retrieved_task.hls.thumbnail_urls or []: print(f" {url}") print(f" Status: {retrieved_task.hls.status}") print(f" Updated at: {retrieved_task.hls.updated_at}") ``` ### Parameters | Name | Type | Required | Description | | ----------------- | --------------------------------- | -------- | ------------------------------------------------------------- | | `task_id` | `str` | Yes | The unique identifier of the video indexing task to retrieve. | | `request_options` | `typing.Optional[RequestOptions]` | No | Request-specific configuration. | ### Return value Returns a `TasksRetrieveResponse` object representing the retrieved video indexing task. The `TasksRetrieveResponse` class extends `VideoIndexingTask` and contains the following properties: | Name | Type | Description | | ----------------- | ------------------------------------------- | ------------------------------------------------------------------------------------- | | `id` | `Optional[str]` | The unique identifier of the task. | | `video_id` | `Optional[str]` | The unique identifier of the video associated with the specified video indexing task. | | `created_at` | `Optional[str]` | The date and time, in the RFC 3339 format, that the task was created. | | `updated_at` | `Optional[str]` | The date and time, in the RFC 3339 format, that the task object was last updated. | | `status` | `Optional[str]` | The status of the video indexing task. | | `index_id` | `Optional[str]` | The unique identifier of the index to which the video must be uploaded. | | `system_metadata` | `Optional[VideoIndexingTaskSystemMetadata]` | System-generated metadata about the video. | | `hls` | `Optional[HlsObject]` | HLS streaming information for the video. | The `VideoIndexingTaskSystemMetadata` class contains the following properties: | Name | Type | Description | | ---------- | ----------------- | -------------------------- | | `duration` | `Optional[float]` | The duration of the video. | | `filename` | `Optional[str]` | The filename of the video. | | `height` | `Optional[int]` | The height of the video. | | `width` | `Optional[int]` | The width of the video. | The `HlsObject` class contains the following properties: | Name | Type | Description | | ---------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `video_url` | `Optional[str]` | The URL of the video for HLS streaming. | | `thumbnail_urls` | `Optional[List[str]]` | An array containing the URL of the thumbnail. | | `status` | `Optional[HlsObjectStatus]` | The encoding status of the video file from its original format to a streamable format. Possible values: `PROCESSING`, `COMPLETE`, `CANCELED`, `ERROR`. | | `updated_at` | `Optional[str]` | The date and time, in the RFC 3339 format, that the encoding status was last updated. | ### API Reference [Retrieve a video indexing task](/v1.3/api-reference/videos/tasks/retrieve). ## Wait for a video indexing task to complete > **Info** > > This method will be removed in a future version. **Description**: This method waits until a video indexing task is completed. It checks the task status at regular intervals by retrieving its details. If you provide a callback function, the method calls it after each status check with the current task object. This allows you to monitor the progress of the task. **Function signature and example**: **`Function signature`** ```python Function signature def wait_for_done( self, task_id: str, *, sleep_interval: float = 5.0, callback: typing.Optional[ typing.Callable[[TasksRetrieveResponse], None] ] = None, request_options: typing.Optional[RequestOptions] = None, ) -> TasksRetrieveResponse ``` **`Python example`** ```Python Python example from twelvelabs import TwelveLabs from twelvelabs.tasks import TasksRetrieveResponse def on_task_update(task: TasksRetrieveResponse): print(f" Status={task.status}") task = client.tasks.wait_for_done(task_id="", callback=on_task_update) if task.status != "ready": raise RuntimeError(f"Indexing failed with status {task.status}") print( f"Upload complete. The unique identifier of your video is {task.video_id}.") ``` ### Parameters | Name | Type | Required | Description | | ----------------- | --------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `task_id` | `str` | Yes | The unique identifier of the task to wait for. | | `sleep_interval` | `float` | No | The time in seconds to wait between status checks. Must be greater than 0. Default: `5.0`. | | `callback` | `Optional` `[Callable` `[[TasksRetrieveResponse], None]]` | No | An optional function to call after each status check, receiving the current task object. Use this to monitor progress. | | `request_options` | `Optional[RequestOptions]` | No | Request-specific configuration. | ### Return value Returns a `TasksRetrieveResponse` object representing the completed task. See the [Retrieve a video indexing task](#retrieve-a-video-indexing-task) section above for complete property details. ## List video indexing tasks > **Info** > > This method will be removed in a future version. **Description**: This method returns a paginated list of the video indexing tasks in your account. By default, the platform returns your video indexing tasks sorted by creation date, with the newest at the top of the list. **Function signature and example**: **`Function signature`** ```python Function signature def list( self, *, page: typing.Optional[int] = None, page_limit: typing.Optional[int] = None, sort_by: typing.Optional[str] = None, sort_option: typing.Optional[str] = None, index_id: typing.Optional[str] = None, status: typing.Optional[ typing.Union[TasksListRequestStatusItem, typing.Sequence[TasksListRequestStatusItem]] ] = None, filename: typing.Optional[str] = None, duration: typing.Optional[float] = None, width: typing.Optional[int] = None, height: typing.Optional[int] = None, created_at: typing.Optional[str] = None, updated_at: typing.Optional[str] = None, request_options: typing.Optional[RequestOptions] = None, ) -> SyncPager[VideoIndexingTask] ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs tasks = client.tasks.list( page=1, page_limit=5, sort_by="created_at", sort_option="desc", index_id="", status=["ready", "indexing"], filename="video.mp4", duration=20, width=640, height=360, created_at="2024-03-01T00:00:00Z", updated_at="2024-03-01T00:00:00Z", ) if len(tasks.items) == 0: print("No tasks in the index, exiting") exit() for task in tasks: print(f"Task ID: {task.id}") print(f"Index ID: {task.index_id}") print(f"Video ID: {task.video_id}") print(f"Status: {task.status}") print("System metadata:") for key, value in (task.system_metadata): print(f" {key}: {value}") print(f"Created at: {task.created_at}") if task.updated_at: print(f"Updated at: {task.updated_at}") ``` ### Parameters | Name | Type | Required | Description | | ----------------- | -------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page` | `typing.Optional[int]` | No | The page number to retrieve. Default: 1. | | `page_limit` | `typing.Optional[int]` | No | The number of items per page. Default: 10. Max: 50. | | `sort_by` | `typing.Optional[str]` | No | The field to sort by: `"created_at"` or `"updated_at"`. Default: `"created_at"`. | | `sort_option` | `typing.Optional[str]` | No | The sort order: `"asc"` or `"desc"`. Default: `"desc"`. | | `index_id` | `typing.Optional[str]` | No | Filter by the unique identifier of an index. | | `status` | `typing.` `Optional` `[typing.Union` `[TasksListRequestStatusItem, typing.Sequence` `[TasksListRequestStatusItem]]]` | No | Filter by task status. Options: `"ready"`, `"uploading"`, `"validating"`, `"pending"`, `"queued"`, `"indexing"`, or `"failed"`. You can specify multiple statuses. | | `filename` | `typing.Optional[str]` | No | Filter by filename. | | `duration` | `typing.Optional[float]` | No | Filter by duration in seconds. | | `width` | `typing.Optional[int]` | No | Filter by video width. | | `height` | `typing.Optional[int]` | No | Filter by video height. | | `created_at` | `typing.Optional[str]` | No | Filter video indexing tasks by the creation date and time, in the RFC 3339 format. The platform returns the video indexing tasks that were created on the specified date at or after the given time. | | `updated_at` | `typing.Optional[str]` | No | Filter video indexing tasks by the last update date and time, in the RFC 3339 format. The platform returns the video indexing tasks that were updated on the specified date at or after the given time. | | `request_options` | `typing.Optional[RequestOptions]` | No | Request-specific configuration. | ### Return value Returns a `SyncPager[VideoIndexingTask]` object that allows you to iterate through the paginated list of video indexing tasks. The `VideoIndexingTask` class contains the following properties: | Name | Type | Description | | ----------------- | ------------------------------------------- | ------------------------------------------------------------------------------------- | | `id` | `Optional[str]` | The unique identifier of the task. | | `video_id` | `Optional[str]` | The unique identifier of the video associated with the specified video indexing task. | | `created_at` | `Optional[str]` | The date and time, in the RFC 3339 format, that the task was created. | | `updated_at` | `Optional[str]` | The date and time, in the RFC 3339 format, that the task object was last updated. | | `status` | `Optional[str]` | The status of the video indexing task. | | `index_id` | `Optional[str]` | The unique identifier of the index to which the video must be uploaded. | | `system_metadata` | `Optional[VideoIndexingTaskSystemMetadata]` | System-generated metadata about the video. | The `VideoIndexingTaskSystemMetadata` class contains the following properties: | Name | Type | Description | | ---------- | ----------------- | -------------------------- | | `duration` | `Optional[float]` | The duration of the video. | | `filename` | `Optional[str]` | The filename of the video. | | `height` | `Optional[int]` | The height of the video. | | `width` | `Optional[int]` | The width of the video. | ### API Reference [List video indexing tasks](/v1.3/api-reference/videos/tasks/list). ## Delete a video indexing task > **Info** > > This method will be removed in a future version. **Description**: This method deletes an existing video indexing task. This action cannot be undone. You can only delete video indexing tasks for which the status is `ready` or `failed`. If the status of your video indexing task is ready, you must first delete the video vector associated with your video indexing task. **Function signature and example**: **`Function signature`** ```python Function signature def delete(self, task_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> None ``` **`Python example`** ```python Python example from twelvelabs import TwelveLabs client.tasks.delete(task_id="") ``` ### Parameters | Name | Type | Required | Description | | ----------------- | --------------------------------- | -------- | ----------------------------------------------------------- | | `task_id` | `str` | Yes | The unique identifier of the video indexing task to delete. | | `request_options` | `typing.Optional[RequestOptions]` | No | Request-specific configuration. | ### Return value `None`. This method doesn't return any data upon successful completion. ### API Reference [Delete a video indexing task](/v1.3/api-reference/videos/tasks/delete). # Error codes This section lists the most common error messages you may encounter while uploading videos. * `video_resolution_too_low` * The resolution of the video is too low. Please upload a video with resolution between 360x360 and 5184x2160. Current resolution is `{current_resolution}`. * `video_resolution_too_high` * The resolution of the video is too high. Please upload a video with resolution between 360x360 and 5184x2160. Current resolution is `{current_resolution}`. * `video_resolution_invalid_aspect_ratio` * The aspect ratio of the video is invalid. Please upload a video with aspect ratio between 1:1 and 2.4:1. Current resolution is `{current_resolution}`. * `video_file_broken` * Cannot read video file. Please check the video file is valid and try again. * `task_cannot_be_deleted` * (Returns raw error message) * `usage_limit_exceeded` * Not enough free credit. Please register a payment method or contact [sales@twelvelabs.io](mailto:sales@twelvelabs.io). * `video_filesize_too_large` * The video is too large. Please use a video with a size less than `{maximum_size}`. The current size is `{current_file_size}`. * `video_duration_too_short` * The video is too short. Please use a video with duration at least \{minimum_duration} seconds. Current duration is \{current_duration} seconds. * `video_duration_too_long` * The video is too long. Please use a video with duration at most \{maximum_duration} seconds. Current duration is \{current_duration} seconds. Note that the minimum and maximum durations depend on the models enabled for your index. For details, see the input requirements of each model on the [Marengo](/v1.3/docs/concepts/models/marengo) and [Pegasus](/v1.3/docs/concepts/models/pegasus/pegasus-1-5#video-file-requirements) pages. If both models are enabled, the most restrictive requirements apply. For a list of general errors that apply to all endpoints, see the [Error codes](/v1.3/api-reference/error-codes) page.