> 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. # Index content > Manage the indexed assets within an index. The `Indexes.IndexedAssets` interface provides methods to manage indexed assets within an index. # Workflow Before you begin, create an index if you don’t have one. [Upload your content](/v1.3/sdk-reference/node-js/upload-content/) using direct or multipart uploads. The platform creates an asset and returns its unique identifier. Asset processing is asynchronous. Poll the [`assets.retrieve`](/v1.3/sdk-reference/node-js/manage-assets#retrieve-an-asset) method until the `status` field is `ready` before proceeding. Index your content using the [`indexes.indexedAssets.create`](/v1.3/sdk-reference/node-js/index-content#create-an-indexed-asset) method. Monitor the indexing status until it shows ready using the [`indexes.indexedAssets.retrieve`](/v1.3/sdk-reference/node-js/index-content#retrieve-an-indexed-asset) method. [Search](/v1.3/sdk-reference/node-js/search) or [analyze](/v1.3/sdk-reference/node-js/analyze-videos) your content. ## Index an asset **Description**: This method indexes an uploaded asset to make it searchable and analyzable. Indexing processes your content and extracts information that enables the platform to search and analyze your videos. This operation is asynchronous. The platform returns an indexed asset ID immediately and processes your content in the background. Monitor the indexing status to know when your content is ready to use. > **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 asset must meet the requirements based on your workflow: * **Search**: [Marengo requirements](/v1.3/docs/concepts/models/marengo/marengo-3-0#video-file-requirements) * **Video analysis**: [Pegasus requirements](/v1.3/docs/concepts/models/pegasus#input-requirements) If you want to both search and analyze your videos, the most restrictive requirements 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( indexId: string, request: TwelvelabsApi.indexes.IndexedAssetsCreateRequest, requestOptions?: IndexedAssets.RequestOptions ): core.HttpResponsePromise ``` **`Index an asset`** ```javascript Index an asset import { TwelveLabs } from "twelvelabs-js"; const indexedAsset = await client.indexes.indexedAssets.create( "", { assetId: "", enableVideoStream: true, } ); console.log(`Indexed Asset ID: ${indexedAsset.id}`); console.log("Indexing started. Monitor status using retrieve method."); ``` ### Parameters | Name | Type | Required | Description | | :--------------- | :------------------------------------------------- | :------- | :-------------------------------- | | `request` | `TwelvelabsApi.indexes.IndexedAssetsCreateRequest` | Yes | Parameters for indexing an asset. | | `requestOptions` | `IndexedAssets.RequestOptions` | No | Request-specific configuration. | The `TwelvelabsApi.indexes.IndexedAssetsCreateRequest` interface has the following properties: | Name | Type | Required | Description | | ------------------- | ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `assetId` | `string` | Yes | The unique identifier of the asset to index. The asset status must be `ready`. Use [`assets.retrieve`](/v1.3/sdk-reference/node-js/manage-assets#retrieve-an-asset) to check the status. | | `enableVideoStream` | `boolean` | No | This parameter indicates if the platform stores the video for streaming. When set to `true`, the platform stores the video, and you can retrieve its URL to access the stream over the HLS protocol. | | `userMetadata` | `TwelvelabsApi.UserMetadata` | No | Metadata that helps you categorize your assets. You can specify a list of keys and values. Keys are strings, and values can be a string, a number, a boolean, or an array of strings. | ### Return value Returns an `HttpResponsePromise` that resolves to a `TwelvelabsApi.indexes.IndexedAssetsCreateResponse` object containing the indexed asset details. The `TwelvelabsApi.indexes.IndexedAssetsCreateResponse` interface contains the following properties: | Name | Type | Description | | --------- | -------- | ------------------------------------------------------------------------------------ | | `id` | `string` | The unique identifier of the indexed asset. Use it to monitor the indexing progress. | | `assetId` | `string` | The unique identifier of the associated asset. | ### API Reference [Index an asset](/v1.3/api-reference/index-content/create) ## Retrieve an indexed asset **Description**: This method retrieves information about an indexed asset, including its status, metadata, and optional embeddings or transcription. Use this method to: * Monitor the indexing progress: * Call this endpoint after creating an indexed asset * Check the `status` field until it shows `ready` * Once ready, your content is available for search and analysis * Retrieve the asset metadata: * Retrieve system metadata (duration, resolution, filename) * Access user-defined metadata * Retrieve the embeddings: * Include the `embeddingOption` parameter to retrieve video embeddings * Requires the Marengo video understanding model to be enabled in your index * Retrieve transcriptions: * Set the `transcription` parameter to `true` to retrieve spoken words from your video ### Function signature and example **`Function signature`** ```javascript Function signature retrieve( indexId: string, indexedAssetId: string, request?: TwelvelabsApi.indexes.IndexedAssetsRetrieveRequest, requestOptions?: IndexedAssets.RequestOptions ): core.HttpResponsePromise ``` **`Monitor indexing status`** ```javascript Monitor indexing status import { TwelveLabs } from "twelvelabs-js"; // Poll until indexing is complete while (true) { const asset = await client.indexes.indexedAssets.retrieve( "", "" ); console.log(`Status: ${asset.status}`); if (asset.status === "ready") { console.log("Indexing complete!"); console.log(`Duration: ${asset.systemMetadata.duration}s`); console.log(`Resolution: ${asset.systemMetadata.width}x${asset.systemMetadata.height}`); break; } else if (asset.status === "failed") { console.log("Indexing failed"); break; } else { await new Promise(resolve => setTimeout(resolve, 5000)); } } ``` **`Retrieve with transcription`** ```javascript Retrieve with transcription import { TwelveLabs } from "twelvelabs-js"; const asset = await client.indexes.indexedAssets.retrieve( "", "", { transcription: true, } ); console.log(`Status: ${asset.status}`); if (asset.transcription) { console.log("Transcription:"); for (const segment of asset.transcription) { console.log(` [${segment.start}s - ${segment.end}s]: ${segment.value}`); } } ``` **`Retrieve with embeddings`** ```javascript Retrieve with embeddings import { TwelveLabs } from "twelvelabs-js"; const asset = await client.indexes.indexedAssets.retrieve( "", "", { embeddingOption: ["visual", "audio"], } ); console.log(`Status: ${asset.status}`); if (asset.embedding) { console.log(`Video embeddings: ${asset.embedding.videoEmbedding.length} segments`); } ``` ### Parameters | Name | Type | Required | Description | | :--------------- | :--------------------------------------------------- | :------- | :------------------------------------------------------------------------------- | | `indexId` | `string` | Yes | The unique identifier of the index to which the indexed asset has been uploaded. | | `indexedAssetId` | `string` | Yes | The unique identifier of the indexed asset to retrieve. | | `request` | `TwelvelabsApi.indexes.IndexedAssetsRetrieveRequest` | Yes | Parameters for retrieving an indexed asset. | | `requestOptions` | `IndexedAssets.RequestOptions` | No | Request-specific configuration. | The `TwelvelabsApi.indexes.IndexedAssetsRetrieveRequest` interface has the following properties: | Name | Type | Required | Description | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------- | | `embeddingOption` | `TwelvelabsApi.indexes.IndexedAssetsRetrieveRequestEmbeddingOptionItem \| TwelvelabsApi.indexes.IndexedAssetsRetrieveRequestEmbeddingOptionItem[]` | No | Specifies which types of embeddings to retrieve. Values: `visual`, `audio`, `transcription` | | `transcription` | `boolean` | No | Indicates whether to retrieve a transcription of the spoken words for the indexed asset. | **Return value**: Returns an `HttpResponsePromise` that resolves to a `TwelvelabsApi.IndexedAssetDetailed` object containing detailed information about the indexed asset. The `TwelvelabsApi.IndexedAssetDetailed` interface extends `TwelvelabsApi.IndexedAsset` and contains the following additional properties: | Name | Type | Description | | --------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `userMetadata` | `Record` | User-defined metadata for the indexed asset. | | `hls` | `TwelvelabsApi.HlsObject` | The platform returns this object only for videos uploaded with the `enableVideoStream` parameter set to `true`. | | `embedding` | `TwelvelabsApi.IndexedAssetDetailedEmbedding` | Contains the embedding and the associated information. The platform returns this field when the `embeddingOption` parameter is specified in the request. | | `transcription` | `TwelvelabsApi.TranscriptionDataItem[]` | A list of transcription segments. The platform returns this field when the `transcription` parameter is set to `true`. | The `IndexedAssetDetailed` interface also inherits all properties from `TwelvelabsApi.IndexedAsset`: | Name | Type | Description | | ---------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of the indexed asset. | | `assetId` | `string` | The unique identifier of the associated asset. | | `createdAt` | `string` | The date and time, in RFC 3339 format, when the indexing task was created. | | `updatedAt` | `string` | The date and time, in RFC 3339 format, when the indexing task was last updated. | | `indexedAt` | `string` | The date and time, in RFC 3339 format, when the indexing task was completed. | | `status` | `TwelvelabsApi.IndexedAssetStatus` | The status of the indexing task. Values: `ready`, `pending`, `queued`, `indexing`, `failed`. | | `systemMetadata` | `TwelvelabsApi.IndexedAssetSystemMetadata` | System-generated metadata about the indexed asset. | The `IndexedAssetSystemMetadata` interface contains the following properties: | Name | Type | Description | | ---------- | -------- | ------------------------------------- | | `filename` | `string` | The filename of the indexed asset. | | `duration` | `number` | The duration of the video in seconds. | | `fps` | `number` | The frames per second of the video. | | `width` | `number` | The width of the video in pixels. | | `height` | `number` | The height of the video in pixels. | | `size` | `number` | The size of the file in bytes. | The `HlsObject` interface contains the following properties: | Name | Type | Description | | --------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `videoUrl` | `string` | The URL of the video. You can use this URL to access the stream over the HLS protocol. | | `thumbnailUrls` | `string[]` | An array containing the URLs of thumbnails. | | `status` | `TwelvelabsApi.HlsObjectStatus` | The encoding status of the video file. Values: `PROCESSING` (video is being encoded), `COMPLETE` (encoding finished), `CANCELED` (encoding was canceled), `ERROR` (encoding error occurred). | | `updatedAt` | `string` | The date and time, in RFC 3339 format, when the encoding status was last updated. | The `TranscriptionDataItem` interface contains the following properties: | Name | Type | Description | | ------- | -------- | ---------------------------------------------------------- | | `start` | `number` | The start of the time range, expressed in seconds. | | `end` | `number` | The end of the time range, expressed in seconds. | | `value` | `string` | Text representing the spoken words within this time range. | ### PI Reference [Retrieve an indexed asset](/v1.3/api-reference/index-content/create) ## Update an indexed asset **Description**: This method updates one or more fields of the metadata of an indexed asset. You can also delete a field by setting it to `null`. **Function signature and example**: **`Function signature`** ```javascript Function signature update( indexId: string, indexedAssetId: string, request: TwelvelabsApi.indexes.IndexedAssetsUpdateRequest, requestOptions?: IndexedAssets.RequestOptions ): core.HttpResponsePromise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; await client.indexes.indexedAssets.update( "", "", { userMetadata: { category: "recentlyAdded", batchNumber: 5, rating: 9.3, needsReview: true, }, } ); console.log("Metadata updated successfully"); ``` ### Parameters | Name | Type | Required | Description | | ---------------- | -------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `indexId` | `string` | Yes | The unique identifier of the index to which the indexed asset has been uploaded. | | `indexedAssetId` | `string` | Yes | The unique identifier of the indexed asset to update. | | `userMetadata` | `Record` | No | User-defined metadata to associate with the indexed asset. Each value is a string, a number, a boolean, or an array of strings. | | `requestOptions` | `IndexedAssets.RequestOptions` | No | Request-specific configuration. | ### Return value Returns a `Promise` that resolves to `void`. ### API Reference [Update indexed asset](/v1.3/api-reference/index-content/update) ## List indexed assets **Description**: This method returns a list of the indexed assets in the specified index. By default, the platform returns your indexed assets sorted by creation date, with the newest at the top of the list. **Function signature and example**: **`Function signature`** ```javascript Function signature list( indexId: string, request?: TwelvelabsApi.indexes.IndexedAssetsListRequest, requestOptions?: IndexedAssets.RequestOptions ): Promise> ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const response = await client.indexes.indexedAssets.list( "", { page: 1, pageLimit: 10, } ); console.log("Indexed assets:"); for await (const asset of response) { console.log(` ID: ${asset.id}`); console.log(` Status: ${asset.status}`); console.log(` Created: ${asset.createdAt}`); } ``` ### Parameters | Name | Type | Required | Description | | :--------------- | :----------------------------------------------- | :------- | :------------------------------------------------------------------------------------------ | | `indexId` | `string` | Yes | The unique identifier of the index for which the platform will retrieve the indexed assets. | | `request` | `TwelvelabsApi.indexes.IndexedAssetsListRequest` | No | Parameters for listing indexed assets. | | `requestOptions` | `IndexedAssets.RequestOptions` | No | Request-specific configuration. | The `TwelvelabsApi.indexes.IndexedAssetsListRequest` interface has the following properties: | Name | Type | Required | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `indexId` | `string` | Yes | The unique identifier of the index for which the platform will retrieve the indexed assets. | | `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. Values: `updated_at`, `created_at`. Default: `created_at`. | | `sortOption` | `string` | No | The sorting direction. Values: `asc`, `desc`. Default: `desc`. | | `status` | `TwelvelabsApi.indexes.IndexedAssetsListRequestStatusItem \| TwelvelabsApi.indexes.IndexedAssetsListRequestStatusItem[]` | No | Filter by one or more indexing task statuses. Values: `ready`, `pending`, `queued`, `indexing`, `failed`. | | `filename` | `string` | No | Filter by filename. | | `duration` | `number` | No | Filter by duration. Expressed in seconds. | | `fps` | `number` | No | Filter by frames per second. | | `width` | `number` | No | Filter by width. | | `height` | `number` | No | Filter by height. | | `size` | `number` | No | Filter by size. Expressed in bytes. | | `createdAt` | `string` | No | Filter indexed assets by the creation date and time of their associated indexing tasks, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"). | | `updatedAt` | `string` | No | Filter indexed assets by the last update date and time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"). This filter applies only to indexed assets updated using the update method. | | `userMetadata` | `Record` | No | Filter by custom user-defined metadata fields. To enable filtering, you must first add user-defined metadata to your video. | ### Return value Returns a `Promise` that resolves to a `Page` object that allows you to iterate through the paginated indexed asset results. The `Page` interface contains the following properties and methods: | Name | Type | Description | | ---------------------- | ------------------ | ---------------------------------------------------------------------------- | | `data` | `T[]` | An array containing the current page of items. | | `hasNextPage()` | `boolean` | Returns whether there is a next page to load. | | `getNextPage()` | `Promise>` | Retrieves the next page and returns the updated `Page` object. | | `Symbol.asyncIterator` | `AsyncIterator` | Allows iteration through all items across all pages using `for await` loops. | The `TwelvelabsApi.IndexedAsset` interface contains the following properties: | Name | Type | Description | | ---------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | A string representing the unique identifier of your indexed asset. | | `assetId` | `string` | The unique identifier of the associated asset. | | `createdAt` | `string` | A string indicating the date and time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), that the indexing task was created. | | `updatedAt` | `string` | A string indicating the date and time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), that the indexing task was last updated. | | `indexedAt` | `string` | A string indicating the date and time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), that the indexing task has been completed. | | `status` | `TwelvelabsApi.IndexedAssetStatus` | The status of the indexing task. Values: `ready`, `pending`, `queued`, `indexing`, `failed`. | | `systemMetadata` | `TwelvelabsApi.IndexedAssetSystemMetadata` | System-generated metadata about the indexed asset. | ### API Reference [List indexed assets](/v1.3/api-reference/index-content/list) ## List indexed assets by asset **Description**: This method returns a list of indexed assets that reference the specified asset. Each entry includes the indexed asset ID and the index it belongs to. **Function signature and example**: **`Function signature`** ```javascript Function signature listByAsset( assetId: string, request?: TwelvelabsApi.indexes.IndexedAssetsListByAssetRequest, requestOptions?: IndexedAssets.RequestOptions ): Promise> ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const response = await client.indexes.indexedAssets.listByAsset( "", { page: 1, pageLimit: 10, } ); console.log("Indexed assets referencing this asset:"); for await (const item of response) { console.log(` Indexed Asset ID: ${item.id}`); console.log(` Index: ${item.index?.name} (${item.index?.id})`); } ``` ### Parameters | Name | Type | Required | Description | | ---------------- | ------------------------------------------------------- | -------- | ----------------------------------------------- | | `assetId` | `string` | Yes | The unique identifier of the asset. | | `request` | `TwelvelabsApi.indexes.IndexedAssetsListByAssetRequest` | No | Parameters for listing indexed assets by asset. | | `requestOptions` | `IndexedAssets.RequestOptions` | No | Request-specific configuration. | The `TwelvelabsApi.indexes.IndexedAssetsListByAssetRequest` interface has the following properties: | 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`. | ### Return value Returns a `Promise` that resolves to a `Page` object that allows you to iterate through the paginated results. The `Page` interface contains the following properties and methods: | Name | Type | Description | | ---------------------- | ------------------ | ---------------------------------------------------------------------------- | | `data` | `T[]` | An array containing the current page of items. | | `hasNextPage()` | `boolean` | Returns whether there is a next page to load. | | `getNextPage()` | `Promise>` | Retrieves the next page and returns the updated `Page` object. | | `Symbol.asyncIterator` | `AsyncIterator` | Allows iteration through all items across all pages using `for await` loops. | The `TwelvelabsApi.IndexedAssetSummary` interface contains the following properties: | Name | Type | Description | | ------- | ---------------------------------------- | --------------------------------------------- | | `id` | `string` | The unique identifier of the indexed asset. | | `index` | `TwelvelabsApi.IndexedAssetSummaryIndex` | The index to which the indexed asset belongs. | The `TwelvelabsApi.IndexedAssetSummaryIndex` interface contains the following properties: | Name | Type | Description | | ------ | -------- | ----------------------------------- | | `id` | `string` | The unique identifier of the index. | | `name` | `string` | The name of the index. | ### API Reference [List indexed assets for an asset](/v1.3/api-reference/index-content/list-indexed-assets-by-asset) ## Delete an indexed asset **Description**: This method deletes all the information about the specified indexed asset. This action cannot be undone. **Function signature and example**: **`Function signature`** ```javascript Function signature delete( indexId: string, indexedAssetId: string, requestOptions?: IndexedAssets.RequestOptions ): core.HttpResponsePromise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; // Delete an indexed asset await client.indexes.indexedAssets.delete( "", "" ); console.log("Indexed asset deleted successfully"); ``` ### Parameters | Name | Type | Required | Description | | ---------------- | ------------------------------ | -------- | -------------------------------------------------------------------------------- | | `indexId` | `string` | Yes | The unique identifier of the index to which the indexed asset has been uploaded. | | `indexedAssetId` | `string` | Yes | The unique identifier of the indexed asset to delete. | | `requestOptions` | `IndexedAssets.RequestOptions` | No | Request-specific configuration. | ### Return value Returns an `HttpResponsePromise` that resolves to `void`. ### API Reference [Delete an indexed asset](/v1.3/api-reference/index-content/delete)