> 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. # List videos GET https://api.twelvelabs.io/v1.3/indexes/{index-id}/videos 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.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. Reference: https://docs.twelvelabs.io/api-reference/videos/list ## Authentication - `x-api-key` header (required) — Your API key. You can find your API key on the API Keys page. ## Request ### Path parameters - `index-id` (string, required) — The unique identifier of the index for which the platform will retrieve the videos. ### Query parameters - `page` (integer, optional, default: 1) — A number that identifies the page to retrieve. **Default**: `1`. - `page_limit` (integer, optional, default: 10) — The number of items to return on each page. **Default**: `10`. **Max**: `50`. - `sort_by` (string, optional, default: 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_option` (string, optional, default: desc) — The sorting direction. The following options are available: - `asc` - `desc` **Default**: `desc`. - `filename` (string, optional) — Filter by filename. - `duration` (IndexesIndexIdVideosGetParametersDuration, optional) — 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. - `fps` (IndexesIndexIdVideosGetParametersFps, optional) — 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. - `width` (IndexesIndexIdVideosGetParametersWidth, optional) — 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. - `height` (IndexesIndexIdVideosGetParametersHeight, optional) — 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. - `size` (IndexesIndexIdVideosGetParametersSize, optional) — 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_at` (string, optional) — 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_at` (string, optional) — 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_metadata` (map from string to IndexesIndexIdVideosGetParametersUserMetadataSchema, optional) — 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 ### 200 The video vectors in the specified index have successfully been retrieved. - `data` (list of videoVector, optional) — An array that contains up to `page_limit` videos. - `page_info` (page_info, optional) — An object that provides information about pagination. ## Errors ### 400 Bad Request Error The request has failed. - `code` (string, optional) — A string representing the code associated with the error. See the [Error codes](/v1.3/api-reference/error-codes) page for details. - `message` (string, optional) — A human-readable string describing the error, intended to be suitable for display in a user interface. ## Types ### IndexesIndexIdVideosGetParametersDuration - `gte` (double, optional) - `lte` (double, optional) ### IndexesIndexIdVideosGetParametersFps - `gte` (double, optional) - `lte` (double, optional) ### IndexesIndexIdVideosGetParametersWidth - `gte` (integer, optional) - `lte` (integer, optional) ### IndexesIndexIdVideosGetParametersHeight - `gte` (integer, optional) - `lte` (integer, optional) ### IndexesIndexIdVideosGetParametersSize - `gte` (double, optional) - `lte` (double, optional) ### IndexesIndexIdVideosGetParametersUserMetadataSchema ### videoVector A video object that contains information about the video. - `_id` (string, optional) — A string representing the unique identifier of a video. The platform creates a new `video_vector` object and assigns it a unique identifier when the video has successfully been indexed. Note that video identifiers are different from task identifiers. - `asset_id` (string, optional) — The unique identifier of the associated asset. - `created_at` (string, optional) — A string indicating the date and time, in the RFC RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), that the video indexing task was created. - `updated_at` (string, optional) — A string indicating the date and time, in the RFC RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), that the video indexing task object was last updated. The platform updates this field every time the video indexing task transitions to a different state. - `indexed_at` (string, optional) — A string indicating the date and time, in the RFC RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), that the video indexing task has been completed. - `system_metadata` (VideoVectorSystemMetadata, optional) — System-generated metadata about the video. ### page_info An object that provides information about pagination. - `limit_per_page` (integer, optional) — The maximum number of items on each page. - `page` (integer, optional) — The page you retrieved. - `total_page` (integer, optional) — The total number of pages. - `total_results` (integer, optional) — The total number of results. ### VideoVectorSystemMetadata System-generated metadata about the video. - `filename` (string, optional) - `duration` (double, optional) - `fps` (double, optional) - `width` (integer, optional) - `height` (integer, optional) - `size` (double, optional) ## Examples **Response** ```json { "data": [ { "_id": "62a17bf847f5678267ec10cc", "asset_id": "62a17bf847f5678267ec10cc", "created_at": "2022-06-09T04:50:00.879Z", "updated_at": "2022-06-09T04:55:57.256Z", "index_id": "62a0906d47f5678267ec10a6", "metadata": { "duration": 531.998133, "filename": "01.mp4", "height": 400, "width": 854 }, "status": "ready" }, { "_id": "62a17bce47f5678267ec10c6", "asset_id": "62a17bce47f5678267ec10c6", "created_at": "2022-06-09T04:49:20.001Z", "updated_at": "2022-06-09T04:54:10.345Z", "index_id": "62a0906d47f5678267ec10a6", "metadata": { "duration": 741.875, "filename": "02.mp4", "height": 480, "width": 854 }, "status": "ready" } ], "page_info": { "limit_per_page": 10, "page": 1, "total_page": 1, "total_results": 2 } } ``` **SDK Code** ```python import requests url = "https://api.twelvelabs.io/v1.3/indexes/6298d673f1090f1100476d4c/videos" querystring = {"filename":"01.mp4","duration":"{\"gte\":10,\"lte\":10}","fps":"{\"gte\":25,\"lte\":25}","width":"{\"gte\":1920,\"lte\":1920}","height":"{\"gte\":1080,\"lte\":1080}","size":"{\"gte\":1048576,\"lte\":1048576}","created_at":"2024-08-16T16:53:59Z","updated_at":"2024-08-16T16:53:59Z"} headers = {"x-api-key": ""} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.twelvelabs.io/v1.3/indexes/6298d673f1090f1100476d4c/videos?filename=01.mp4&duration=%7B%22gte%22%3A10%2C%22lte%22%3A10%7D&fps=%7B%22gte%22%3A25%2C%22lte%22%3A25%7D&width=%7B%22gte%22%3A1920%2C%22lte%22%3A1920%7D&height=%7B%22gte%22%3A1080%2C%22lte%22%3A1080%7D&size=%7B%22gte%22%3A1048576%2C%22lte%22%3A1048576%7D&created_at=2024-08-16T16%3A53%3A59Z&updated_at=2024-08-16T16%3A53%3A59Z'; const options = {method: 'GET', headers: {'x-api-key': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.twelvelabs.io/v1.3/indexes/6298d673f1090f1100476d4c/videos?filename=01.mp4&duration=%7B%22gte%22%3A10%2C%22lte%22%3A10%7D&fps=%7B%22gte%22%3A25%2C%22lte%22%3A25%7D&width=%7B%22gte%22%3A1920%2C%22lte%22%3A1920%7D&height=%7B%22gte%22%3A1080%2C%22lte%22%3A1080%7D&size=%7B%22gte%22%3A1048576%2C%22lte%22%3A1048576%7D&created_at=2024-08-16T16%3A53%3A59Z&updated_at=2024-08-16T16%3A53%3A59Z" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("x-api-key", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.twelvelabs.io/v1.3/indexes/6298d673f1090f1100476d4c/videos?filename=01.mp4&duration=%7B%22gte%22%3A10%2C%22lte%22%3A10%7D&fps=%7B%22gte%22%3A25%2C%22lte%22%3A25%7D&width=%7B%22gte%22%3A1920%2C%22lte%22%3A1920%7D&height=%7B%22gte%22%3A1080%2C%22lte%22%3A1080%7D&size=%7B%22gte%22%3A1048576%2C%22lte%22%3A1048576%7D&created_at=2024-08-16T16%3A53%3A59Z&updated_at=2024-08-16T16%3A53%3A59Z") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["x-api-key"] = '' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.twelvelabs.io/v1.3/indexes/6298d673f1090f1100476d4c/videos?filename=01.mp4&duration=%7B%22gte%22%3A10%2C%22lte%22%3A10%7D&fps=%7B%22gte%22%3A25%2C%22lte%22%3A25%7D&width=%7B%22gte%22%3A1920%2C%22lte%22%3A1920%7D&height=%7B%22gte%22%3A1080%2C%22lte%22%3A1080%7D&size=%7B%22gte%22%3A1048576%2C%22lte%22%3A1048576%7D&created_at=2024-08-16T16%3A53%3A59Z&updated_at=2024-08-16T16%3A53%3A59Z") .header("x-api-key", "") .asString(); ``` ```php request('GET', 'https://api.twelvelabs.io/v1.3/indexes/6298d673f1090f1100476d4c/videos?filename=01.mp4&duration=%7B%22gte%22%3A10%2C%22lte%22%3A10%7D&fps=%7B%22gte%22%3A25%2C%22lte%22%3A25%7D&width=%7B%22gte%22%3A1920%2C%22lte%22%3A1920%7D&height=%7B%22gte%22%3A1080%2C%22lte%22%3A1080%7D&size=%7B%22gte%22%3A1048576%2C%22lte%22%3A1048576%7D&created_at=2024-08-16T16%3A53%3A59Z&updated_at=2024-08-16T16%3A53%3A59Z', [ 'headers' => [ 'x-api-key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.twelvelabs.io/v1.3/indexes/6298d673f1090f1100476d4c/videos?filename=01.mp4&duration=%7B%22gte%22%3A10%2C%22lte%22%3A10%7D&fps=%7B%22gte%22%3A25%2C%22lte%22%3A25%7D&width=%7B%22gte%22%3A1920%2C%22lte%22%3A1920%7D&height=%7B%22gte%22%3A1080%2C%22lte%22%3A1080%7D&size=%7B%22gte%22%3A1048576%2C%22lte%22%3A1048576%7D&created_at=2024-08-16T16%3A53%3A59Z&updated_at=2024-08-16T16%3A53%3A59Z"); var request = new RestRequest(Method.GET); request.AddHeader("x-api-key", ""); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["x-api-key": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/indexes/6298d673f1090f1100476d4c/videos?filename=01.mp4&duration=%7B%22gte%22%3A10%2C%22lte%22%3A10%7D&fps=%7B%22gte%22%3A25%2C%22lte%22%3A25%7D&width=%7B%22gte%22%3A1920%2C%22lte%22%3A1920%7D&height=%7B%22gte%22%3A1080%2C%22lte%22%3A1080%7D&size=%7B%22gte%22%3A1048576%2C%22lte%22%3A1048576%7D&created_at=2024-08-16T16%3A53%3A59Z&updated_at=2024-08-16T16%3A53%3A59Z")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```