> 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. # Retrieve an asset GET https://api.twelvelabs.io/v1.3/assets/{asset_id} This method retrieves details about the specified asset. Reference: https://docs.twelvelabs.io/api-reference/manage-assets/retrieve ## Authentication - `x-api-key` header (required) — Your API key. You can find your API key on the API Keys page. ## Request ### Path parameters - `asset_id` (string, required) — The unique identifier of the asset to retrieve. ## Response ### 200 The asset has been successfully retrieved. - `_id` (string, optional) — The unique identifier of the asset. - `method` (enum, optional) — Indicates how the asset was uploaded or imported. **Values**: - `direct`: Uploaded from your local file system - `url`: Uploaded from a publicly accessible URL - `multipart`: Uploaded using the multipart upload flow - `connector`: Imported through a data connector - Allowed values: `direct`, `url`, `multipart`, `connector` - `status` (enum, optional) — Indicates the current processing status of the asset. A newly uploaded asset starts in the `processing` status and transitions asynchronously to `ready` on success or to `failed` on error, typically within a few seconds to a few minutes. Poll the [Retrieve an asset](/v1.3/api-reference/upload-content/direct-uploads/retrieve) endpoint until the status is `ready` before you use the asset in different workflows. **Values**: - `processing`: The asset is not yet usable. This can mean the upload is still in progress (for example, the platform is still fetching the file from a URL, or a multipart upload has not completed), or the upload has finished and the platform is validating the file. The `technical_metadata` field is omitted from the response. - `ready`: The platform validated the asset successfully, and the asset is ready to use. - `failed`: The platform could not process the file. The `error` field describes the reason, and the `technical_metadata` field may be partially populated. - Allowed values: `failed`, `processing`, `ready` - `filename` (string, optional) — The name of the file used to create the asset. - `file_type` (string, optional) — The MIME type of the asset file. For documents, this is `application/pdf`, `text/plain`, or `text/markdown`. - `created_at` (string, optional) — The date and time, in RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when the asset was created. - `user_metadata` (map from string to UserMetadataValue, optional) — User-defined metadata for this asset. This field is absent when no metadata has been set. - `source` (AssetSource, optional) — Describes where the asset came from. Present only for assets imported through a connector; absent for assets uploaded directly to the `/assets` endpoint. - `hls` (AssetHLS, optional) — HLS streaming details for video and audio assets. Present only when HLS generation has been requested. - `thumbnail` (AssetThumbnail, optional) — Thumbnail details for the asset. Present only when thumbnail generation has been requested. PDF files use the first page for the representative thumbnail; text and Markdown files do not produce thumbnails. - `technical_metadata` (TechnicalMetadata, optional) — Technical metadata read from the source file of the asset, covering the container, video and audio streams, image properties, document properties, and derived attributes. The platform populates this object asynchronously after the upload completes. It is omitted from the response while the status of the asset is `processing`, and it may be partially populated when the status is `failed`. A field is absent when it does not apply to the type of the asset or when the source file did not contain the corresponding information. - `size` (long, optional) — The file size of the asset in bytes. The platform sets this value when the asset reaches the `ready` status. - `duration` (double, optional) — The duration of the asset in seconds. Only present for video and audio assets; absent for images and documents. The platform sets this value when the asset reaches the `ready` status. - `error` (AssetError, optional) — The reason the processing failed. The platform returns this field only when `status` is `failed`. ## 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. ### 404 Not Found Error The specified resource does not exist. - `code` (string, optional) — Represents 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. ## Types ### UserMetadataValue A single metadata value: a string, a number, a boolean, or an array of strings. The platform stores the value with the type you send. It rejects a nested object and an array that contains anything but strings. Send an integer wider than 53 bits (-9007199254740991 to 9007199254740991) and any identifier you want preserved verbatim as a string. ### AssetSource Describes where an asset came from. The platform sets this field for assets imported through a connector; it is absent for assets uploaded directly to the `/assets` endpoint. - `type` (enum, optional) — The kind of source. - Allowed values: `connector` - `details` (AssetSourceDetails, optional) — Provider-specific details about the origin of the file. The fields depend on the value of the `type` field. ### AssetHLS HLS streaming details for video and audio assets. Present only when HLS generation has been requested. - `manifest_url` (string, optional) — The URL of the HLS manifest file for streaming. Only present when the status of the HLS stream is `ready`. - `status` (enum, optional) — The status of the HLS stream. **Values**: - `pending`: The platform has not yet started HLS generation - `processing`: The platform is generating HLS segments - `ready`: The HLS stream is ready for playback - `error`: HLS generation failed - Allowed values: `pending`, `processing`, `ready`, `error` ### AssetThumbnail Thumbnail details for the asset. Present only when thumbnail generation has been requested. PDF files use the first page for the representative thumbnail; text and Markdown files do not produce thumbnails. - `representative_url` (string, optional) — The URL of the representative thumbnail image. Only present when the status of the thumbnail is `ready`. - `status` (enum, optional) — The status of the thumbnail. **Values**: - `pending`: The platform has not yet started thumbnail generation - `processing`: The platform is generating the thumbnail - `ready`: The thumbnail is ready - `error`: Thumbnail generation failed - Allowed values: `pending`, `processing`, `ready`, `error` ### TechnicalMetadata Technical metadata read from the source file of the asset, covering the container, video and audio streams, image properties, document properties, and derived attributes. The platform populates this object asynchronously after the upload completes. It is omitted from the response while the status of the asset is `processing`, and it may be partially populated when the status is `failed`. A field is absent when it does not apply to the type of the asset or when the source file did not contain the corresponding information. - `file_size_bytes` (long, optional) — The size of the source file in bytes. - `file_mime_type` (string, optional) — The MIME type detected for the source file. - `file_container_format` (string, optional) — The container format of the source file. When a container maps to several format names, the platform reports them as a comma-separated list. - `container_creation_time` (string, optional) — The creation time recorded in the source file container, in RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when present. - `video_streams` (list of VideoStream, optional) — The video streams contained in the media file. - `video_codec` (string, optional) — The codec of the primary video stream. - `video_width` (integer, optional) — The pixel width of the primary video stream. - `video_height` (integer, optional) — The pixel height of the primary video stream. - `video_fps` (double, optional) — The frame rate of the primary video stream, in frames per second. - `video_duration_seconds` (double, optional) — The duration of the primary video stream, in seconds. - `video_bitrate_bps` (long, optional) — The bit rate of the primary video stream, in bits per second. - `audio_streams` (list of AudioStream, optional) — The audio streams contained in the media file. - `audio_codec` (string, optional) — The codec of the primary audio stream. - `audio_sample_rate` (integer, optional) — The sample rate of the primary audio stream, in hertz. - `audio_channels` (integer, optional) — The number of channels in the primary audio stream. - `audio_duration_seconds` (double, optional) — The duration of the primary audio stream, in seconds. - `start_timecode` (string, optional) — The starting SMPTE timecode of the media, when present. - `timecode_source` (string, optional) — The source from which the starting timecode was derived. - `drop_frame` (boolean, optional) — Whether the timecode uses drop-frame numbering. - `image_width` (integer, optional) — The pixel width of the image. - `image_height` (integer, optional) — The pixel height of the image. - `image_format` (string, optional) — The format of the image. - `image_orientation` (integer, optional) — The EXIF orientation value of the image. - `image_color_space` (string, optional) — The color space of the image. - `image_bit_depth` (integer, optional) — The bit depth per channel of the image. - `is_hdr` (boolean, optional) — Whether the media is high dynamic range (HDR). - `has_audio` (boolean, optional) — Whether the media contains at least one audio stream. - `has_alpha` (boolean, optional) — Whether the image contains an alpha (transparency) channel. - `is_animated` (boolean, optional) — Whether the image is animated (for example, an animated GIF or WebP). - `total_video_streams` (integer, optional) — The total number of video streams in the media file. - `total_audio_streams` (integer, optional) — The total number of audio streams in the media file. - `storage_aspect_ratio` (double, optional) — The storage aspect ratio of the video (pixel width divided by pixel height). - `geospatial_latitude` (double, optional) — The GPS latitude embedded in the source media, in decimal degrees. Present only when the source media carries location metadata. - `geospatial_longitude` (double, optional) — The GPS longitude embedded in the source media, in decimal degrees. Present only when the source media carries location metadata. - `geospatial_altitude_meters` (double, optional) — The GPS altitude embedded in the source media, in meters. Present only when the source media carries location metadata. - `document_page_count` (integer, optional, nullable) — The number of pages in the PDF file. - `document_pdf_version` (string, optional, nullable) — The PDF version specified in the file. - `document_page_width_pt` (double, optional, nullable) — The width of the first page, in points. - `document_page_height_pt` (double, optional, nullable) — The height of the first page, in points. - `document_is_tagged` (boolean, optional, nullable) — Whether the PDF file is tagged for accessibility. An explicit `false` is meaningful. - `document_is_encrypted` (boolean, optional, nullable) — Whether the PDF file is encrypted. An explicit `false` is meaningful. - `document_language` (string, optional, nullable) — The language specified in the PDF file, when present. - `document_title` (string, optional, nullable) — The title from the PDF metadata, when present. - `document_author` (string, optional, nullable) — The author from the PDF metadata, when present. - `document_subject` (string, optional, nullable) — The subject from the PDF metadata, when present. - `document_keywords` (string, optional, nullable) — The keywords from the PDF metadata, when present. - `document_creator_tool` (string, optional, nullable) — The application that created the PDF file, when present. - `document_producer` (string, optional, nullable) — The application that produced the PDF file, when present. - `document_creation_date` (string, optional, nullable) — The normalized creation date from the PDF file, in RFC 3339 format, when present. - `document_modification_date` (string, optional, nullable) — The normalized modification date from the PDF file, in RFC 3339 format, when present. ### AssetError An object that describes why the processing failed. - `message` (string, required) — A human-readable message describing the failure, such as a corrupted or unsupported file, a file the platform could not access, or a video that failed a playability check. The exact text is not part of the contract. Do not parse it. ### AssetSourceDetails Provider-specific details about the origin of the file. The fields depend on the value of the `type` field. - `provider` (enum, optional) — The data connector provider. - Allowed values: `google_drive` - `source_id` (string, optional) — The identifier of the file at the provider. For Google Drive, this is the identifier Google Drive assigns to the file. - `original_filename` (string, optional) — The name of the file at the provider when it was imported. - `source_link` (string, optional) — A link to the file at the provider. ### VideoStream The technical properties of a single video stream within the media file. - `index` (integer, optional) — The zero-based index of the stream within the media file. - `codec` (string, optional) — The codec of the video stream. - `width` (integer, optional) — The pixel width of the video stream. - `height` (integer, optional) — The pixel height of the video stream. - `fps` (double, optional) — The nominal frame rate of the video stream, in frames per second. - `avg_fps` (double, optional) — The average frame rate of the video stream, in frames per second. - `duration_seconds` (double, optional) — The duration of the video stream, in seconds. - `bitrate_bps` (long, optional) — The bit rate of the video stream, in bits per second. - `rotation` (integer, optional) — The rotation applied to the video stream, in degrees. - `pixel_aspect_ratio` (string, optional) — The pixel (sample) aspect ratio of the video stream. - `display_aspect_ratio` (string, optional) — The display aspect ratio of the video stream. - `scan_type` (string, optional) — The scan type of the video stream (for example, progressive or interlaced). - `pixel_format` (string, optional) — The pixel format of the video stream. - `bit_depth` (integer, optional) — The bit depth per color component of the video stream. - `color_range` (string, optional) — The color range of the video stream. - `color_transfer` (string, optional) — The color transfer characteristics of the video stream. - `color_space` (string, optional) — The color space of the video stream. - `color_primaries` (string, optional) — The color primaries of the video stream. ### AudioStream The technical properties of a single audio stream within the media file. - `index` (integer, optional) — The zero-based index of the stream within the media file. - `codec` (string, optional) — The codec of the audio stream. - `codec_long` (string, optional) — The descriptive long name of the audio codec. - `sample_rate` (integer, optional) — The sample rate of the audio stream, in hertz. - `bit_depth` (integer, optional) — The bit depth of the audio stream. - `channels` (integer, optional) — The number of channels in the audio stream. - `channel_layout` (string, optional) — The channel layout of the audio stream. - `bitrate_bps` (long, optional) — The bit rate of the audio stream, in bits per second. - `language` (string, optional) — The language of the audio stream, when present. - `duration_seconds` (double, optional) — The duration of the audio stream, in seconds. ## Examples ### Video file **Response** ```json { "_id": "6298d673f1090f1100476d4c", "method": "direct", "status": "ready", "filename": "my-video.mp4", "file_type": "video/mp4", "created_at": "2022-06-02T10:30:00Z", "technical_metadata": { "file_size_bytes": 104857600, "file_mime_type": "video/mp4", "video_codec": "h264", "video_width": 1920, "video_height": 1080, "video_fps": 29.97, "video_duration_seconds": 120.5, "audio_codec": "aac", "audio_sample_rate": 48000, "audio_channels": 2 }, "size": 104857600, "duration": 120.5 } ``` **SDK Code** ```python Video file import requests url = "https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c" headers = {"x-api-key": ""} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript Video file const url = 'https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c'; 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 Video file package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c" 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 Video file require 'uri' require 'net/http' url = URI("https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c") 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 Video file import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c") .header("x-api-key", "") .asString(); ``` ```php Video file request('GET', 'https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c', [ 'headers' => [ 'x-api-key' => '', ], ]); echo $response->getBody(); ``` ```csharp Video file using RestSharp; var client = new RestClient("https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c"); var request = new RestRequest(Method.GET); request.AddHeader("x-api-key", ""); IRestResponse response = client.Execute(request); ``` ```swift Video file import Foundation let headers = ["x-api-key": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c")! 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() ``` ### PDF file **Response** ```json { "_id": "6298d673f1090f1100476d4e", "method": "direct", "status": "ready", "filename": "report.pdf", "file_type": "application/pdf", "created_at": "2026-08-12T10:30:00Z", "technical_metadata": { "file_size_bytes": 1048576, "file_mime_type": "application/pdf", "document_page_count": 12, "document_pdf_version": "1.7", "document_page_width_pt": 612, "document_page_height_pt": 792, "document_is_tagged": true, "document_is_encrypted": false, "document_language": "en-US", "document_title": "Quarterly report", "document_author": "Ada Lovelace", "document_subject": "Results", "document_keywords": "quarterly, results", "document_creator_tool": "Docs", "document_producer": "PDFium", "document_creation_date": "2026-08-10T05:15:16Z", "document_modification_date": "2026-08-11T01:02:03Z" }, "size": 1048576 } ``` **SDK Code** ```python PDF file import requests url = "https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c" headers = {"x-api-key": ""} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript PDF file const url = 'https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c'; 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 PDF file package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c" 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 PDF file require 'uri' require 'net/http' url = URI("https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c") 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 PDF file import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c") .header("x-api-key", "") .asString(); ``` ```php PDF file request('GET', 'https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c', [ 'headers' => [ 'x-api-key' => '', ], ]); echo $response->getBody(); ``` ```csharp PDF file using RestSharp; var client = new RestClient("https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c"); var request = new RestRequest(Method.GET); request.AddHeader("x-api-key", ""); IRestResponse response = client.Execute(request); ``` ```swift PDF file import Foundation let headers = ["x-api-key": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c")! 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() ``` ### Text file **Response** ```json { "_id": "6298d673f1090f1100476d50", "method": "direct", "status": "ready", "filename": "notes.txt", "file_type": "text/plain", "created_at": "2026-08-12T10:30:00Z", "technical_metadata": { "file_size_bytes": 2048, "file_mime_type": "text/plain" }, "size": 2048 } ``` **SDK Code** ```python Text file import requests url = "https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c" headers = {"x-api-key": ""} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript Text file const url = 'https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c'; 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 Text file package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c" 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 Text file require 'uri' require 'net/http' url = URI("https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c") 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 Text file import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c") .header("x-api-key", "") .asString(); ``` ```php Text file request('GET', 'https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c', [ 'headers' => [ 'x-api-key' => '', ], ]); echo $response->getBody(); ``` ```csharp Text file using RestSharp; var client = new RestClient("https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c"); var request = new RestRequest(Method.GET); request.AddHeader("x-api-key", ""); IRestResponse response = client.Execute(request); ``` ```swift Text file import Foundation let headers = ["x-api-key": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/assets/6298d673f1090f1100476d4c")! 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() ```