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
  • TwelveLabs API
    • Introduction
    • Authentication
  • API Reference
    • Manage indexes
    • Upload content
    • Index content
      • POSTIndex an asset
      • GETRetrieve an indexed asset
      • GETList indexed assets
      • DELDelete an indexed asset
      • PATCHPartial update indexed asset
      • GETList indexed assets for an asset
    • Manage videos
    • Manage entities
    • Any-to-video search
    • Create embeddings v2
    • Create embeddings v1
    • Analyze and segment videos
    • Error codes
LogoLogo
Sample appsIntegrationsDiscordPlaygroundDevEx repo
API ReferenceIndex content

Retrieve an indexed asset

GET
https://api.twelvelabs.io/v1.3/indexes/:index-id/indexed-assets/:indexed-asset-id
GET
/v1.3/indexes/:index-id/indexed-assets/:indexed-asset-id
$curl -G https://api.twelvelabs.io/v1.3/indexes/6298d673f1090f1100476d4c/indexed-assets/6298d673f1090f1100476d4c \
>     -H "x-api-key: <apiKey>" \
>     -d transcription=true
1{
2  "_id": "61e17be5777e6caec646fa07",
3  "asset_id": "6298d673f1090f1100476d4c",
4  "created_at": "2022-01-14T13:34:29Z",
5  "embedding": {
6    "model_name": "marengo3.0",
7    "video_embedding": {
8      "segments": [
9        {
10          "embedding_option": "visual",
11          "embedding_scope": "clip",
12          "end_offset_sec": 7.5666666,
13          "float": [
14            -0.04747168,
15            0.030509098,
16            0.032282468
17          ],
18          "start_offset_sec": 0
19        }
20      ]
21    }
22  },
23  "hls": {
24    "video_url": "https://d2cp8xx7n5vxnu.cloudfront.net/6298aa0b535db125bf6e1d10/64902a28fb01304dd47be3cb/stream/c924f34a-144e-41df-bf2a-c693703fa134.m3u8",
25    "thumbnail_urls": [
26      "https://d2cp8xx7n5vxnu.cloudfront.net/6298aa0b535db125bf6e1d10/64902a28fb01304dd47be3cb/thumbnails/c924f34a-144e-41df-bf2a-c693703fa134.0000001.jpg"
27    ],
28    "status": "COMPLETE",
29    "updated_at": "2024-01-16T07:59:40.879Z"
30  },
31  "indexed_at": "2022-01-14T14:05:55Z",
32  "status": "ready",
33  "system_metadata": {
34    "filename": "IOKgzkakhlk.mp4",
35    "duration": 3747.841667,
36    "fps": 29.97002997002997,
37    "width": 482,
38    "height": 360
39  },
40  "transcription": [
41    {
42      "start": 0,
43      "end": 10.5,
44      "value": "Hello, how are you?"
45    },
46    {
47      "start": 10.5,
48      "end": 15.2,
49      "value": "I'm fine, thank you."
50    }
51  ],
52  "updated_at": "2022-01-14T13:34:29Z",
53  "user_metadata": {
54    "category": "recentlyAdded",
55    "batchNumber": 5,
56    "rating": 9.3,
57    "needsReview": true
58  }
59}
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
Was this page helpful?
Previous

List indexed assets

Next
Built with

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

Authentication

x-api-keystring
Your API key. <Note title="Note"> You can find your API key on the <a href="https://playground.twelvelabs.io/dashboard/api-keys" target="_blank">API Keys</a> page. </Note>

Path parameters

index-idstringRequired
The unique identifier of the index to which the indexed asset has been uploaded.
indexed-asset-idstringRequired
The unique identifier of the indexed asset to retrieve.

Query parameters

embedding_optionlist of enumsOptional
Specifies which types of embeddings to retrieve. Values: `visual`, `audio`, `transcription`. For details, see the [Embedding options](/v1.3/docs/concepts/modalities#embedding-options) section. <Note title="Note"> To retrieve embeddings for a video, it must be indexed using the Marengo video understanding model. For details on enabling this model for an index, see the [Create an index](/reference/create-index) page. </Note>
Allowed values:
transcriptionbooleanOptional
Specifies whether to retrieve a transcription of the spoken words.

Response

The specified indexed asset information has successfully been retrieved.
_idstring
A string representing the unique identifier of your indexed asset.
asset_idstring
The unique identifier of the associated asset.
created_atstring

A string indicating the date and time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), that the indexing task was created.

embeddingobject

Contains the embedding and the associated information. The platform returns this field when the embedding_option parameter is specified in the request.

hlsobject

The platform returns this object only for the videos that you uploaded with the enable_video_stream parameter set to true.

indexed_atstring

A string indicating the date and time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), that the indexing task has been completed.

statusenum
The status of the indexing task.
Allowed values:
system_metadataobject

System-generated metadata about the indexed asset.

transcriptionlist of objects

An array of objects that contains the transcription. For each time range for which the platform finds spoken words, it returns an object that contains the fields below. If the platform doesn’t find any spoken words, the data field is set to null.

updated_atstring

A string indicating the date and time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), that the indexing task was last updated. The platform updates this field every time the indexing task transitions to a different state.

user_metadatamap from strings to any

User-defined metadata for this indexed asset.

Errors

400
Bad Request Error
404
Not Found Error

Your API key.

Note

You can find your API key on the API Keys page.

Specifies which types of embeddings to retrieve. Values: visual, audio, transcription. For details, see the Embedding options section.

Note

To retrieve embeddings for a video, it must be indexed using the Marengo video understanding model. For details on enabling this model for an index, see the Create an index page.