---
title: "List assets"
method: GET
path: "/assets"
tags: ["assets"]
---

# List assets

`GET /assets`

This method returns a list of assets in your account.

The platform returns your assets sorted by creation date, with the newest at the top of the list.

## Query parameters

- `page` integer
- `page_limit` integer
- `asset_ids` string[]
- `asset_types` AssetsGetParametersAssetTypesSchemaItems[]
- `filename` string

## Headers

- `x-api-key` string, required

## Response `200`

The assets have been successfully retrieved.

- AssetsListResponse200
  - `data` AssetDetail[] — An array containing the assets.
    - `_id` string — The unique identifier of the asset.
    - `method` 'direct' | 'url' | 'multipart' — Indicates how you uploaded the asset. **Values**: - `direct`: Uploaded from your local file system - `url`: Uploaded from a publicly accessible URL - `multipart`: Uploaded using the multipart upload flow
    - `status` 'failed' | 'processing' | 'ready' — 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 downstream 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.
    - `filename` string — The name of the file used to create the asset.
    - `file_type` string — The MIME type of the asset file.
    - `created_at` string, date-time — The date and time, in RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when the asset was created.
    - `user_metadata` UserMetadata — Metadata that helps you categorize your assets. The object contains user-defined keys and values, where keys are strings and values are one of `string`, `integer`, `float`, or `boolean`. **Example**: ```JSON "user_metadata": { "category": "recentlyAdded", "batchNumber": 5, "rating": 9.3, "needsReview": true } ``` <Note title="Note"> To store other types of data, such as objects or arrays, convert your data into string values before sending it. </Note>
    - `source` 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` 'connector' — The kind of source.
      - `details` AssetSourceDetails — Provider-specific details about the origin of the file. The fields depend on the value of the `type` field.
        - `provider` 'google_drive' — The data connector provider.
        - `source_id` string — The identifier of the file at the provider. For Google Drive, this is the Drive file identifier.
        - `original_filename` string — The name of the file at the provider when it was imported.
        - `source_link` string — A link to the file at the provider.
    - `hls` AssetHLS — HLS streaming details for the asset. Present only when HLS generation has been requested. Omitted otherwise.
      - `manifest_url` string — The URL of the HLS manifest file for streaming. Only present when the status of the HLS stream is `ready`.
      - `status` 'pending' | 'processing' | 'ready' | 'error' — 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
    - `thumbnail` AssetThumbnail — Thumbnail details for the asset. Present only when thumbnail generation has been requested. Omitted otherwise.
      - `representative_url` string — The URL of the representative thumbnail image. Only present when the status of the thumbnail is `ready`.
      - `status` 'pending' | 'processing' | 'ready' | 'error' — 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
    - `technical_metadata` TechnicalMetadata — Technical metadata read from the media file of the asset, covering the container, the individual video and audio streams, image 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 media type of the asset, or when the source file did not carry the corresponding information.
      - `file_size_bytes` integer — The size of the source media file in bytes.
      - `file_mime_type` string — The MIME type detected for the source media file.
      - `file_container_format` string — The container format of the source media file. When a container maps to several format names, the platform reports them as a comma-separated list.
      - `container_creation_time` string, date-time — The creation time recorded in the media container, in RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when present.
      - `video_streams` VideoStream[] — The video streams contained in the media file.
        - `index` integer — The zero-based index of the stream within the media file.
        - `codec` string — The codec of the video stream.
        - `width` integer — The pixel width of the video stream.
        - `height` integer — The pixel height of the video stream.
        - `fps` number, double — The nominal frame rate of the video stream, in frames per second.
        - `avg_fps` number, double — The average frame rate of the video stream, in frames per second.
        - `duration_seconds` number, double — The duration of the video stream, in seconds.
        - `bitrate_bps` integer — The bit rate of the video stream, in bits per second.
        - `rotation` integer — The rotation applied to the video stream, in degrees.
        - `pixel_aspect_ratio` string — The pixel (sample) aspect ratio of the video stream.
        - `display_aspect_ratio` string — The display aspect ratio of the video stream.
        - `scan_type` string — The scan type of the video stream (for example, progressive or interlaced).
        - `pixel_format` string — The pixel format of the video stream.
        - `bit_depth` integer — The bit depth per color component of the video stream.
        - `color_range` string — The color range of the video stream.
        - `color_transfer` string — The color transfer characteristics of the video stream.
        - `color_space` string — The color space of the video stream.
        - `color_primaries` string — The color primaries of the video stream.
      - `video_codec` string — The codec of the primary video stream.
      - `video_width` integer — The pixel width of the primary video stream.
      - `video_height` integer — The pixel height of the primary video stream.
      - `video_fps` number, double — The frame rate of the primary video stream, in frames per second.
      - `video_duration_seconds` number, double — The duration of the primary video stream, in seconds.
      - `video_bitrate_bps` integer — The bit rate of the primary video stream, in bits per second.
      - `audio_streams` AudioStream[] — The audio streams contained in the media file.
        - `index` integer — The zero-based index of the stream within the media file.
        - `codec` string — The codec of the audio stream.
        - `codec_long` string — The descriptive long name of the audio codec.
        - `sample_rate` integer — The sample rate of the audio stream, in hertz.
        - `bit_depth` integer — The bit depth of the audio stream.
        - `channels` integer — The number of channels in the audio stream.
        - `channel_layout` string — The channel layout of the audio stream.
        - `bitrate_bps` integer — The bit rate of the audio stream, in bits per second.
        - `language` string — The language of the audio stream, when present.
        - `duration_seconds` number, double — The duration of the audio stream, in seconds.
      - `audio_codec` string — The codec of the primary audio stream.
      - `audio_sample_rate` integer — The sample rate of the primary audio stream, in hertz.
      - `audio_channels` integer — The number of channels in the primary audio stream.
      - `audio_duration_seconds` number, double — The duration of the primary audio stream, in seconds.
      - `start_timecode` string — The starting SMPTE timecode of the media, when present.
      - `timecode_source` string — The source from which the starting timecode was derived.
      - `drop_frame` boolean — Whether the timecode uses drop-frame numbering.
      - `image_width` integer — The pixel width of the image.
      - `image_height` integer — The pixel height of the image.
      - `image_format` string — The format of the image.
      - `image_orientation` integer — The EXIF orientation value of the image.
      - `image_color_space` string — The color space of the image.
      - `image_bit_depth` integer — The bit depth per channel of the image.
      - `is_hdr` boolean — Whether the media is high dynamic range (HDR).
      - `has_audio` boolean — Whether the media contains at least one audio stream.
      - `has_alpha` boolean — Whether the image contains an alpha (transparency) channel.
      - `is_animated` boolean — Whether the image is animated (for example, an animated GIF or WebP).
      - `total_video_streams` integer — The total number of video streams in the media file.
      - `total_audio_streams` integer — The total number of audio streams in the media file.
      - `storage_aspect_ratio` number, double — The storage aspect ratio of the video (pixel width divided by pixel height).
      - `geospatial_latitude` number, double — The GPS latitude embedded in the source media, in decimal degrees. Present only when the source media carries location metadata.
      - `geospatial_longitude` number, double — The GPS longitude embedded in the source media, in decimal degrees. Present only when the source media carries location metadata.
      - `geospatial_altitude_meters` number, double — The GPS altitude embedded in the source media, in meters. Present only when the source media carries location metadata.
    - `size` integer — The file size of the asset in bytes. The platform finalizes this value when the asset reaches the `ready` status.
    - `duration` number, double — The duration of the asset in seconds. Only present for video and audio assets; absent for images. The platform finalizes this value when the asset reaches the `ready` status.
    - `error` AssetError — An object that describes why an asset failed processing.
      - `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.
  - `page_info` PageInfo — An object that provides information about pagination.
    - `limit_per_page` integer — The maximum number of items on each page.
    - `page` integer — The page you retrieved.
    - `total_page` integer — The total number of pages.
    - `total_results` integer — The total number of results.

## Other responses

- `400` — The request has failed.

---

[API](https://skmtc.net/twelvelabs/apis/twelvelabs-api.md) · [All operations](https://skmtc.net/twelvelabs/apis/twelvelabs-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/twelvelabs/twelvelabs-api/revisions/5dbd6e8473c9/schema)