For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Sample appsIntegrationsDiscordPlaygroundDevEx repo
GuidesSDK ReferenceAPI Reference
GuidesSDK ReferenceAPI Reference
  • Python SDK
    • The TwelveLabs class
    • Manage indexes
    • Upload content
    • Index content
    • Manage videos
    • Manage entities
    • Search
    • Create embeddings v2
    • Create embeddings v1
    • Analyze and segment videos
  • Node.js SDK
    • The TwelveLabs class
    • Manage indexes
    • Upload content
    • Index content
    • Manage videos
    • Manage entities
    • Search
    • Create embeddings v2
    • Create embeddings v1
    • Analyze and segment videos
LogoLogo
Sample appsIntegrationsDiscordPlaygroundDevEx repo
On this page
  • Methods
  • Create an index
  • Parameters
  • Return value
  • API Reference
  • Related guide
  • Retrieve an index
  • Parameters
  • Return value
  • API Reference
  • List indexes
  • Parameters
  • Return value
  • API Reference
  • Update an index
  • Parameters
  • Return value
  • API Reference
  • Delete an index
  • Parameters
  • Return value
  • API Reference
  • Error codes
Node.js SDK

Manage indexes

Was this page helpful?
Previous

Upload content

Next
Built with

An index is a basic unit for organizing and storing video data consisting of video embeddings and metadata. Indexes facilitate information retrieval and processing. The IndexesWrapper class provides methods to manage your indexes.

Methods

Create an index

Description: This method creates a new index based on the provided parameters.

Function signature and example:

1create(
2    request: TwelvelabsApi.IndexesCreateRequest, requestOptions?: Indexes.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.IndexesCreateResponse>

Parameters

NameTypeRequiredDescription
requestTwelvelabsApi.IndexesCreateRequestYesParameters for creating the index.
requestOptionsIndexes.RequestOptionsNoRequest-specific configuration.

The TwelvelabsApi.IndexesCreateRequest interface has the following properties:

NameTypeRequiredDescription
indexNamestringYesThe name of the new index. Use a succinct and descriptive name.
modelsTwelvelabsApi.IndexesCreateRequestModelsItem[]YesA list of objects specifying the video understanding models and the model options you want to enable for this index. Each object is a dictionary with two keys:
- modelName: The name of the model to enable. The following models are available:
  - marengo3.0: Enhanced model with sports intelligence and extended content support.
  - pegasus1.2: A model that analyzes multiple modalities to generate contextually relevant text based on the content of your videos.

- modelOptions: Specifies which modalities the platform analyzes. Values: visual, audio. For more details, see the model options section.
addonsstring[]NoA list of add-ons to enable, such as "thumbnail". If omitted, no add-ons are enabled.
Note

You cannot change the model configuration after creating the index.

Return value

Returns an HttpResponsePromise that resolves to a TwelvelabsApi.IndexesCreateResponse instance containing a field named id representing the unique identifier of the newly created index.

API Reference

Create an index.

Related guide

Indexes.

Retrieve an index

Description: This method retrieves details of a specific index.

Function signature and example:

1retrieve(indexId: string, requestOptions?: Indexes.RequestOptions): core.HttpResponsePromise<TwelvelabsApi.IndexSchema>

Parameters

NameTypeRequiredDescription
indexIdstringYesThe unique identifier of the index you want to retrieve.
requestOptionsIndexes.RequestOptionsNoRequest-specific configuration.

Return value

Returns an HttpResponsePromise that resolves to a TwelvelabsApi.IndexSchema object representing the retrieved index.

The TwelvelabsApi.IndexSchema interface contains the following properties:

NameTypeDescription
idstringThe unique identifier of the index. It is assigned by the platform when an index is created.
createdAtstringThe date and time, in the RFC 3339 format, that the index was created.
updatedAtstringThe date and time, in the RFC 3339 format, that the index has been updated.
expiresAtstringThe date and time, in the RFC 3339 format, when your index will expire. If you’re on the Free plan, the platform retains your index data for 90 days from creation. If you’re on the Developer plan, this field is set to null, indicating no expiration.
indexNamestringThe name of the index.
totalDurationnumberThe total duration, in seconds, of the videos in the index.
videoCountnumberThe number of videos uploaded to this index.
modelsTwelvelabsApi.IndexModelsItem[]An array containing the list of the video understanding models enabled for this index.
addonsstring[]The list of the add-ons that are enabled for this index.

The TwelvelabsApi.IndexModelsItem interface contains the following properties:

NameTypeDescription
modelNamestringThe name of the model.
modelOptionsstring[]An array of strings that contains the model options enabled for this index.

API Reference

Retrieve an index.

List indexes

Description: This method retrieves a paginated list of indexes based on the provided parameters. By default, the platform returns your indexes sorted by creation date, with the newest at the top of the list.

Function signature and example:

1  list(
2    request?: TwelvelabsApi.IndexesListRequest,
3    requestOptions?: Indexes.RequestOptions
4  ): Promise<core.Page<TwelvelabsApi.IndexSchema>>

Parameters

NameTypeRequiredDescription
requestTwelvelabsApi.IndexesListRequestNoParameters for retrieving the list of indexes. Default: {}.
requestOptionsIndexes.RequestOptionsNoRequest-specific configuration. Default:{}.

The IndexesListRequest interface defines the parameters for listing indexes:

NameTypeRequiredDescription
pagenumberNoThe page number to retrieve. Default: 1.
pageLimitnumberNoThe number of items to return on each page. Default: 10. Max: 50.
sortBystringNoThe field to sort on. The following options are available: “updated_at” - Sorts by the time when the item was updated, “created_at” - Sorts by the time when the item was created. Default: “created_at”.
sortOptionstringNoThe sorting direction. The following options are available: “asc”, “desc”. Default: “desc”.
indexNamestringNoFilter by the name of an index.
modelOptionsstringNoFilter by the model options. When filtering by multiple model options, the values must be comma-separated. Example: "visual,audio").
modelFamilystringNoFilter by the model family. This parameter can take one of the following values: “marengo” or “pegasus”. You can specify a single value.
createdAtstringNoFilter indexes by the creation date and time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”). The platform returns the indexes that were created on the specified date at or after the given time.
updatedAtstringNoFilter indexes by the last update date and time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”). The platform returns the indexes that were last updated on the specified date at or after the given time.

Return value

Returns a Promise that resolves to a core.Page<TwelvelabsApi.IndexSchema> instance, representing the indexes that match the specified criteria. See the Retrieve an index section above for complete property details.

The Page class contains the following properties and methods:

NameTypeDescription
dataT[]An array containing the current page of items.
getNextPage()Promise<this>Retrieves the next page and returns the updated Page object.
hasNextPage()booleanReturns whether there is a next page to load.
Symbol.asyncIteratorAsyncIterator<T>Allows iteration through all items across all pages using for await loops.

API Reference

List indexes.

Update an index

Description: This method updates the name of an existing index.

Function signature and example:

1update(indexId: string, request: TwelvelabsApi.IndexesUpdateRequest, requestOptions?: Indexes.RequestOptions): core.HttpResponsePromise<void>

Parameters

NameTypeRequiredDescription
indexIdstringYesThe unique identifier of the index to update.
requestTwelvelabsApi.IndexesUpdateRequestYesThe request object containing the update parameters.
request.indexNamestringYesThe new name of the index.
requestOptionsIndexes.RequestOptionsNoRequest-specific configuration options.

The TwelvelabsApi.IndexesUpdateRequest interface contains the following properties:

NameTypeDescription
indexNamestringThe new name of the index.

Return value

Returns an HttpResponsePromise that resolves to void. This method doesn’t return any data upon successful completion.

API Reference

Update an index.

Delete an index

Description: This method deletes an existing index.

Function signature and example:

1delete(indexId: string, requestOptions?: Indexes.RequestOptions): core.HttpResponsePromise<void>

Parameters

NameTypeRequiredDescription
indexIdstringYesThe unique identifier of the index to delete.
requestOptionsIndexes.RequestOptionsNoRequest-specific configuration.

Return value

Returns an HttpResponsePromise that resolves to void. This method doesn’t return any data upon successful completion.

API Reference

Delete an index.

Error codes

This section lists the most common error messages you may encounter while managing indexes.

  • index_option_cannot_be_changed
    • Index option cannot be changed. Please remove index_options parameter and try again. If you want to change index option, please create new index.
  • index_engine_cannot_be_changed
    • Index engine cannot be changed. Please remove engine_id parameter and try again. If you want to change engine, please create new index.
  • index_name_already_exists
    • Index name {index_name} already exists. Please use another unique name and try again.

For a list of general errors that apply to all endpoints, see the Error codes page.