> This page is for version v1.3 (default).
> For other versions, use one of these documentation indexes:
> - v1.3 (default): https://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://docs.twelvelabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://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 `TasksWrapper` class provides methods to manage your video indexing tasks.

# Methods

## Create a video indexing task

> **Info**
>
> This method will be removed in a future version. New implementations should use [direct](/v1.3/sdk-reference/node-js/upload-content/direct-uploads) or [multipart](/v1.3/sdk-reference/node-js/upload-content/multipart-uploads) uploads followed by [separate indexing](/v1.3/sdk-reference/node-js/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 the format 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`**

```javascript Function signature
create(request: TwelvelabsApi.TasksCreateRequest, requestOptions?: Tasks.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.TasksCreateResponse>;
```

**`Node.js example`**

```javascript Node.js example
import { TwelveLabs, TwelvelabsApi } from "twelvelabs-js";

const task = await client.tasks.create({
  indexId: "<YOUR_INDEX_ID>",
  videoUrl: "<YOUR_VIDEO_URL>"
});
console.log(`Created task: id=${task.id}`);
```

### Parameters

| Name             | Type                 | Required | Description                                          |
| :--------------- | :------------------- | :------- | :--------------------------------------------------- |
| `request`        | `TasksCreateRequest` | Yes      | Parameters for creating the new video indexing task. |
| `requestOptions` | `RequestOptions`     | No       | Request-specific configuration.                      |

The `TasksCreateRequest` interface defines the parameters for creating a new video indexing task:

| Name                | Type                            | Required | Description                                                                                                                                                                                                                                                                 |
| ------------------- | ------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `indexId`           | `string`                        | Yes      | The unique identifier of the index to which the video will be uploaded.                                                                                                                                                                                                     |
| `videoFile`         | `File \| fs.ReadStream \| Blob` | No       | The video file to upload. This parameter can be a `File`, an `fs.ReadStream`, or a `Blob`.                                                                                                                                                                                  |
| `videoUrl`          | `string`                        | No       | The publicly accessible URL of the video you want to upload.                                                                                                                                                                                                                |
| `enableVideoStream` | `boolean`                       | 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. For details, see the [Retrieve video information](/v1.3/sdk-reference/node-js/manage-videos#retrieve-video-information) section. |
| `userMetadata`      | `string`                        | No       | Metadata that helps you categorize your videos. You can specify a stringified list of keys and values.                                                                                                                                                                      |

### Return value

Returns a `Promise` that resolves to a `TasksCreateResponse` instance.

The `TasksCreateResponse` interface contains the following properties:

| Name      | Type     | Description                                                                  |
| --------- | -------- | ---------------------------------------------------------------------------- |
| `id`      | `string` | The unique identifier of your video indexing task.                           |
| `videoId` | `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`**

```javascript Function signature
retrieve(taskId: string, requestOptions?: Tasks.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.TasksRetrieveResponse>;
```

**`Node.js Example`**

```javascript Node.js Example
import { TwelveLabs, TwelvelabsApi } from "twelvelabs-js";

const retrievedTask = await client.tasks.retrieve("<YOUR_VIDEO_INDEXING_TASK_ID>");
console.log(`Task ID=${retrievedTask.id}`);
console.log(`Index ID: ${retrievedTask.indexId}`);
console.log(`Video ID: ${retrievedTask.videoId}`);
console.log(`Status: ${retrievedTask.status}`);
if (retrievedTask.systemMetadata) {
    console.log("System metadata:");
    for (const [key, value] of Object.entries(retrievedTask.systemMetadata)) {
        console.log(` ${key}: ${value}`);
    }
}
if (retrievedTask.hls) {
    console.log("HLS:");
    console.log(` Video URL: ${retrievedTask.hls.videoUrl}`);
    console.log(" Thumbnail URLs:");
    for (const url of retrievedTask.hls.thumbnailUrls || []) {
        console.log(` ${url}`);
    }
    console.log(` Status: ${retrievedTask.hls.status}`);
    console.log(` Updated at: ${retrievedTask.hls.updatedAt}`);
}
console.log(`Created at: ${retrievedTask.createdAt}`);
console.log(`Updated at: ${retrievedTask.updatedAt}`);
```

### Parameters

| Name             | Type             | Required | Description                                                   |
| :--------------- | :--------------- | :------- | :------------------------------------------------------------ |
| `taskId`         | `string`         | Yes      | The unique identifier of the video indexing task to retrieve. |
| `requestOptions` | `RequestOptions` | No       | Request-specific configuration.                               |

### Return value

Returns a `Promise` that resolves to a `TasksRetrieveResponse` instance representing the retrieved video indexing task..

The `TasksRetrieveResponse` interface extends `VideoIndexingTask` and contains the following properties:

| Name             | Type                              | Description                                                                           |
| ---------------- | --------------------------------- | ------------------------------------------------------------------------------------- |
| `id`             | `string`                          | The unique identifier of the task.                                                    |
| `videoId`        | `string`                          | The unique identifier of the video associated with the specified video indexing task. |
| `createdAt`      | `string`                          | The date and time, in the RFC 3339 format, that the task was created.                 |
| `updatedAt`      | `string`                          | The date and time, in the RFC 3339 format, that the task object was last updated.     |
| `status`         | `string`                          | The status of the video indexing task.                                                |
| `indexId`        | `string`                          | The unique identifier of the index to which the video must be uploaded.               |
| `systemMetadata` | `VideoIndexingTaskSystemMetadata` | System-generated metadata about the video.                                            |
| `hls`            | `HlsObject`                       | HLS streaming information for the video.                                              |

The `VideoIndexingTaskSystemMetadata` interface contains the following properties:

| Name       | Type     | Description                |
| ---------- | -------- | -------------------------- |
| `duration` | `number` | The duration of the video. |
| `filename` | `string` | The filename of the video. |
| `height`   | `number` | The height of the video.   |
| `width`    | `number` | The width of the video.    |

The `HlsObject` interface contains the following properties:

| Name            | Type       | Description                                                                            |
| --------------- | ---------- | -------------------------------------------------------------------------------------- |
| `videoUrl`      | `string`   | The URL of the video for HLS streaming.                                                |
| `thumbnailUrls` | `string[]` | An array containing the URL of the thumbnail.                                          |
| `status`        | `string`   | The encoding status of the video file from its original format to a streamable format. |
| `updatedAt`     | `string`   | 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`**

```javascript Function signature
waitForDone(taskId: string, options?: {
sleepInterval?: number;
callback?: (task: TwelvelabsApi.TasksRetrieveResponse) => void | Promise<void>;
}, requestOptions?: Tasks.RequestOptions): Promise<TwelvelabsApi.TasksRetrieveResponse>;
```

**`Node.js example`**

```javascript Node.js example
import { TwelveLabs, TwelvelabsApi } from "twelvelabs-js";

const task = await client.tasks.waitForDone("<YOUR_TASK_ID>", {
    sleepInterval: 5,
    callback: (task: TwelvelabsApi.TasksRetrieveResponse) => {
        console.log(`  Status=${task.status}`);
    },
});

if (task.status !== "ready") {
    throw new Error(`Indexing failed with status ${task.status}`);
}
console.log(
    `Upload complete. The unique identifier of your video is ${task.videoId}`,
);
```

### Parameters

| Name                    | Type                                                     | Required | Description                                                                                                              |
| :---------------------- | :------------------------------------------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------- |
| `taskId`                | `string`                                                 | Yes      | The unique identifier of the task to wait for.                                                                           |
| `options`               | `object`                                                 | No       | Options for the wait operation.                                                                                          |
| `options.sleepInterval` | `number`                                                 | No       | The time in seconds to wait between status checks. Must be greater than 0. Default: 5.0.                                 |
| `options.callback`      | `(task: TasksRetrieveResponse) => void \| Promise<void>` | No       | An optional function to call after each status check. It receives the current task object. Use this to monitor progress. |
| `requestOptions`        | `RequestOptions`                                         | No       | Request-specific configuration.                                                                                          |

### Return value

A `Promise` that resolves to a `TasksRetrieveResponse` 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 based on the provided parameters. 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`**

```javascript Function signature
list(request?: TwelvelabsApi.TasksListRequest, requestOptions?: Tasks.RequestOptions): Promise<core.Page<TwelvelabsApi.VideoIndexingTask>>;
```

**`Node.js example`**

```javascript Node.js example
import { TwelveLabs } from "twelvelabs-js";

const tasksPager = await client.tasks.list({
  page: 1,
  pageLimit: 10,
  sortBy: "created_at",
  sortOption: "desc",
  indexId: "<YOUR_INDEX_ID>",
  filename: "01.mp4",
  duration: 531.998133,
  width: 640,
  height: 360,
  createdAt: "2024-03-01T00:00:00Z",
  updatedAt: "2024-03-01T00:00:00Z"
});

for await (const task of tasksPager) {
  console.log(`Task ID=${task.id}`);
  console.log(`Index ID: ${task.indexId}`);
  console.log(`Video ID: ${task.videoId}`);
  console.log(`Status: ${task.status}`);

  if (task.systemMetadata) {
    console.log("System metadata:");
    for (const [key, value] of Object.entries(task.systemMetadata)) {
      console.log(`  ${key}: ${value}`);
    }
  }

  console.log(`Created at: ${task.createdAt}`);
  console.log(`Updated at: ${task.updatedAt}`);
}
```

### Parameters

| Name             | Type               | Required | Description                                                |
| :--------------- | :----------------- | :------- | :--------------------------------------------------------- |
| `request`        | `TasksListRequest` | No       | Parameters for filtering the list of tasks. Default: `{}`. |
| `requestOptions` | `RequestOptions`   | No       | Request-specific configuration.                            |

The `TasksListRequest` interface defines the parameters for listing video indexing tasks:

| Name         | Type                                                         | Required | Description                                                                                                                                                                                             |
| ------------ | ------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page`       | `number`                                                     | No       | A number that identifies the page to retrieve. Default: `1`.                                                                                                                                            |
| `pageLimit`  | `number`                                                     | No       | The number of items to return on each page. Default: `10`. Max: `50`.                                                                                                                                   |
| `sortBy`     | `string`                                                     | No       | The field to sort on. Available options: `updated_at`, `created_at`. Default: `created_at`.                                                                                                             |
| `sortOption` | `string`                                                     | No       | The sorting direction. Available options: `asc`, `desc`. Default: `desc`.                                                                                                                               |
| `indexId`    | `string`                                                     | No       | Filter by the unique identifier of an index.                                                                                                                                                            |
| `status`     | `TasksListRequestStatusItem \| TasksListRequestStatusItem[]` | No       | Filter by one or more video indexing task statuses. Available options: `ready`, `uploading`, `validating`, `pending`, `queued`, `indexing`, `failed`.                                                   |
| `filename`   | `string`                                                     | No       | Filter by filename.                                                                                                                                                                                     |
| `duration`   | `number`                                                     | No       | Filter by duration. Expressed in seconds.                                                                                                                                                               |
| `width`      | `number`                                                     | No       | Filter by width.                                                                                                                                                                                        |
| `height`     | `number`                                                     | No       | Filter by height.                                                                                                                                                                                       |
| `createdAt`  | `string`                                                     | 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.    |
| `updatedAt`  | `string`                                                     | 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. |

### Return value

Returns a `Promise` that resolves to a `Page<VideoIndexingTask>` object that implements `AsyncIterable`, allowing you to iterate through the results.

The `VideoIndexingTask` interface contains the following properties:

| Name             | Type                              | Description                                                                           |
| ---------------- | --------------------------------- | ------------------------------------------------------------------------------------- |
| `id`             | `string`                          | The unique identifier of the task.                                                    |
| `videoId`        | `string`                          | The unique identifier of the video associated with the specified video indexing task. |
| `createdAt`      | `string`                          | The date and time, in the RFC 3339 format, that the task was created.                 |
| `updatedAt`      | `string`                          | The date and time, in the RFC 3339 format, that the task object was last updated.     |
| `status`         | `string`                          | The status of the video indexing task.                                                |
| `indexId`        | `string`                          | The unique identifier of the index to which the video must be uploaded.               |
| `systemMetadata` | `VideoIndexingTaskSystemMetadata` | System-generated metadata about the video.                                            |

The `VideoIndexingTaskSystemMetadata` interface contains the following properties:

| Name       | Type     | Description                |
| ---------- | -------- | -------------------------- |
| `duration` | `number` | The duration of the video. |
| `filename` | `string` | The filename of the video. |
| `height`   | `number` | The height of the video.   |
| `width`    | `number` | 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`**

```javascript Function signature
delete(taskId: string, requestOptions?: Tasks.RequestOptions): core.HttpResponsePromise<void>;
```

**`Node.js example`**

```javascript Node.js example
import { TwelveLabs } from "twelvelabs-js";

await client.tasks.delete("<YOUR_TASK_ID>");
```

### Parameters

| Name             | Type             | Required | Description                                                 |
| :--------------- | :--------------- | :------- | :---------------------------------------------------------- |
| `taskId`         | `string`         | Yes      | The unique identifier of the video indexing task to delete. |
| `requestOptions` | `RequestOptions` | No       | Request-specific configuration.                             |

### Return value

Returns a `Promise` that resolves to `void`. 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.