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
    • Manage videos
      • The video object
      • GETList videos
      • GETRetrieve video information
      • PATCHPartial update video information
      • DELDelete video information
    • Manage entities
    • Any-to-video search
    • Create embeddings v2
    • Create embeddings v1
    • Analyze and segment videos
    • Error codes
LogoLogo
Sample appsIntegrationsDiscordPlaygroundDevEx repo
API ReferenceManage videos

List videos

GET
https://api.twelvelabs.io/v1.3/indexes/:index-id/videos
GET
/v1.3/indexes/:index-id/videos
$curl -G https://api.twelvelabs.io/v1.3/indexes/6298d673f1090f1100476d4c/videos \
>     -H "x-api-key: <apiKey>" \
>     -d filename=01.mp4 \
>     -d "duration[gte]=10" \
>     -d "duration[lte]=10" \
>     -d "fps[gte]=25" \
>     -d "fps[lte]=25" \
>     -d "width[gte]=1920" \
>     -d "width[lte]=1920" \
>     -d "height[gte]=1080" \
>     -d "height[lte]=1080" \
>     -d "size[gte]=1048576" \
>     -d "size[lte]=1048576" \
>     --data-urlencode created_at=2024-08-16T16:53:59Z \
>     --data-urlencode updated_at=2024-08-16T16:53:59Z
1{
2  "data": [
3    {
4      "_id": "62a17bf847f5678267ec10cc",
5      "asset_id": "62a17bf847f5678267ec10cc",
6      "created_at": "2022-06-09T04:50:00.879Z",
7      "updated_at": "2022-06-09T04:55:57.256Z"
8    },
9    {
10      "_id": "62a17bce47f5678267ec10c6",
11      "asset_id": "62a17bce47f5678267ec10c6",
12      "created_at": "2022-06-09T04:49:20.001Z",
13      "updated_at": "2022-06-09T04:54:10.345Z"
14    }
15  ],
16  "page_info": {
17    "limit_per_page": 10,
18    "page": 1,
19    "total_page": 1,
20    "total_results": 2
21  }
22}
<Info>This method will be deprecated in a future version. New implementations should use the [List indexed assets](/v1.3/api-reference/index-content/list) method.</Info> This method returns a list of the videos in the specified index. By default, the platform returns your videos sorted by creation date, with the newest at the top of the list.
Was this page helpful?
Previous

Retrieve video information

Next
Built with
This method will be deprecated in a future version. New implementations should use the List indexed assets method.

This method returns a list of the videos in the specified index. By default, the platform returns your videos sorted by creation date, with the newest at the top of the list.

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 for which the platform will retrieve the videos.

Query parameters

pageintegerOptionalDefaults to 1

A number that identifies the page to retrieve.

Default: 1.

page_limitintegerOptionalDefaults to 10

The number of items to return on each page.

Default: 10. Max: 50.

sort_bystringOptionalDefaults to created_at
The field to sort on. The following options are available: - `updated_at`: Sorts by the time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when the item was updated. - `created_at`: Sorts by the time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when the item was created. **Default**: `created_at`.
sort_optionstringOptionalDefaults to desc
The sorting direction. The following options are available: - `asc` - `desc` **Default**: `desc`.
filenamestringOptional
Filter by filename.
durationobjectOptional

Filter by duration in seconds. Pass an object with gte and/or lte for range filtering. For exact match, set both to the same value.

fpsobjectOptional

Filter by frames per second. Pass an object with gte and/or lte for range filtering. For exact match, set both to the same value.

widthobjectOptional

Filter by width in pixels. Pass an object with gte and/or lte for range filtering. For exact match, set both to the same value.

heightobjectOptional

Filter by height in pixels. Pass an object with gte and/or lte for range filtering. For exact match, set both to the same value.

sizeobjectOptional

Filter by size in bytes. Pass an object with gte and/or lte for range filtering. For exact match, set both to the same value.

created_atstringOptional

Filter videos by the creation date and time of their associated indexing tasks, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”). The platform returns the videos whose indexing tasks were created on the specified date at or after the given time.

updated_atstringOptional
This filter applies only to videos updated using the [`PUT`](/v1.3/api-reference/videos/update) method of the `/indexes/{index-id}/videos/{video-id}` endpoint. It filters videos by the last update date and time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"). The platform returns the video indexing tasks that were last updated on the specified date at or after the given time.
user_metadatamap from strings to strings or doubles or booleansOptional
To enable filtering by custom fields, you must first add user-defined metadata to your video by calling the [`PUT`](/v1.3/api-reference/videos/update) method of the `/indexes/:index-id/videos/:video-id` endpoint. Examples: - To filter on a string: `?category=recentlyAdded` - To filter on an integer: `?batchNumber=5` - To filter on a float: `?rating=9.3` - To filter on a boolean: `?needsReview=true`

Response

The video vectors in the specified index have successfully been retrieved.
datalist of objects

An array that contains up to page_limit videos.

page_infoobject
An object that provides information about pagination.

Errors

400
Bad Request Error

Your API key.

Note

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

The field to sort on. The following options are available:

  • updated_at: Sorts by the time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the item was updated.
  • created_at: Sorts by the time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”), when the item was created.

Default: created_at.

The sorting direction. The following options are available:

  • asc
  • desc

Default: desc.

This filter applies only to videos updated using the PUT method of the /indexes/{index-id}/videos/{video-id} endpoint. It filters videos by the last update date and time, in the RFC 3339 format (“YYYY-MM-DDTHH:mm:ssZ”). The platform returns the video indexing tasks that were last updated on the specified date at or after the given time.

To enable filtering by custom fields, you must first add user-defined metadata to your video by calling the PUT method of the /indexes/:index-id/videos/:video-id endpoint.

Examples:

  • To filter on a string: ?category=recentlyAdded
  • To filter on an integer: ?batchNumber=5
  • To filter on a float: ?rating=9.3
  • To filter on a boolean: ?needsReview=true