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 using direct or multipart uploads. The platform creates an asset and return its unique identifier.

Index your content using the indexes.indexedAssets.create method.

Monitor the indexing status until it shows ready using the indexes.indexedAssets.retrieve method.

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.

Your asset must meet the requirements based on your workflow:

Search: Marengo requirements
Video analysis: Pegasus requirements

If you want to both search and analyze your videos, the most restrictive requirements apply.

Function signature and example:

1 create(
2     indexId: string,
3     request: TwelvelabsApi.indexes.IndexedAssetsCreateRequest,
4     requestOptions?: IndexedAssets.RequestOptions
5 ): core.HttpResponsePromise<TwelvelabsApi.indexes.IndexedAssetsCreateResponse>

Parameters:

Name	Type	Required	Description
`indexId`	`string`	Yes	The unique identifier of the index to which the asset will be indexed.
`assetId`	`string`	Yes	The unique identifier of the asset to index.
`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.
`requestOptions`	`IndexedAssets.RequestOptions`	No	Request-specific configuration.

Return value: Returns a Promise that resolves to an IndexedAssetsCreateResponse object containing the indexed asset details.

The 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.

API Reference: Index an asset

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:

1 retrieve(
2     indexId: string,
3     indexedAssetId: string,
4     request?: TwelvelabsApi.indexes.IndexedAssetsRetrieveRequest,
5     requestOptions?: IndexedAssets.RequestOptions
6 ): core.HttpResponsePromise<TwelvelabsApi.IndexedAssetDetailed>

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.
`embeddingOption`	`TwelvelabsApi.indexes.IndexedAssetsRetrieveRequestEmbeddingOptionItem \| TwelvelabsApi.indexes.IndexedAssetsRetrieveRequestEmbeddingOptionItem[]`	No	Specifies which types of embeddings to retrieve. Values vary by model version: - Marengo 3.0: `visual`, `audio`, `transcription` - Marengo 2.7: `visual-text`, `audio` To retrieve embeddings, the video must be indexed using the Marengo model.
`transcription`	`boolean`	No	Indicates whether to retrieve a transcription of the spoken words for the indexed asset.
`requestOptions`	`IndexedAssets.RequestOptions`	No	Request-specific configuration.

Return value: Returns a Promise that resolves to an IndexedAssetDetailed object containing detailed information about the indexed asset.

The IndexedAssetDetailed interface extends IndexedAsset and contains the following additional properties:

Name	Type	Description
`userMetadata`	`Record<string, any>`	User-generated metadata about 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 IndexedAsset:

Name	Type	Description
`id`	`string`	The unique identifier of the indexed 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.

API Reference: Retrieve an indexed asset

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:

1 list(
2     indexId: string,
3     request?: TwelvelabsApi.indexes.IndexedAssetsListRequest,
4     requestOptions?: IndexedAssets.RequestOptions
5 ): Promise<core.Page<TwelvelabsApi.IndexedAsset>>

Parameters:

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<string, any>`	No	Filter by custom user-defined metadata fields. To enable filtering, you must first add user-defined metadata to your video.
`requestOptions`	`IndexedAssets.RequestOptions`	No	Request-specific configuration.

Return value: Returns a Promise that resolves to a Page<IndexedAsset> object that allows you to iterate through the paginated indexed asset results.

The Page<T> 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<Page<T>>`	Retrieves the next page and returns the updated `Page` object.
`[Symbol.asyncIterator]()`	`AsyncIterator<T>`	Allows iteration through all items across all pages using `for await` loops.

The IndexedAsset interface contains the following properties:

Name	Type	Description
`id`	`string`	A string representing the unique identifier of your indexed 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

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:

1 update(
2     indexId: string,
3     indexedAssetId: string,
4     request: TwelvelabsApi.indexes.IndexedAssetsUpdateRequest,
5     requestOptions?: IndexedAssets.RequestOptions
6 ): core.HttpResponsePromise<void>

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<string, any>`	No	User-defined metadata to associate with the indexed asset. You can use strings, integers, floats, and booleans as values.
`requestOptions`	`IndexedAssets.RequestOptions`	No	Request-specific configuration.

Return value: Returns a Promise that resolves to void.

API Reference: Update indexed 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:

1 delete(
2     indexId: string,
3     indexedAssetId: string,
4     requestOptions?: IndexedAssets.RequestOptions
5 ): core.HttpResponsePromise<void>

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

API Reference: Delete an indexed asset