---
title: "List your videos | GPT-Video API reference"
description: "Lists the videos you uploaded or imported, newest first, a page at a time."
url: "https://www.gpt-video.com/developers/api/list-assets"
operation: "list_assets"
method: "GET"
path: "/v1/assets"
scope: "clips:read"
---

Do not assume endpoints have parameters other than the ones explicitly specified.

# List your videos

Operation id `list_assets`. Request `GET /v1/assets`.

Lists the videos you uploaded or imported, newest first, a page at a time.

Beta. This endpoint is supported and can gain new fields. If a change would break your code, we tell you before it takes effect and list it in the changelog.

## About

Use it to find the video to analyze: any of these ids can be the source of a project. The list holds the videos that came from you, through complete_upload (`POST /v1/uploads/{uploadId}/complete`), import_asset or the GPT-Video app. Files the service makes from them, such as converted copies and exports, are not listed; get_asset (`GET /v1/assets/{assetId}`) reads them by id. Use search to find a video by its title.

## Example use

A script that watches a folder of new recordings lists the videos already uploaded and compares their file names with the files on disk. It uploads only the ones that are missing, then creates a project for each.

## Endpoint

```text
GET https://api.gpt-video.com/v1/assets
```

- Scope `clips:read`.
- Rate limit 120 requests a minute for each key and 240 for each account, shared by every `read` call. See [rate limits](/developers/rate-limits.md).
- No `Idempotency-Key`.

## Parameters

### Query

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | Optional | How many items to return, from 1 to 100. Defaults to 20. From 1 to 100. Default `20`. |
| `cursor` | string | Optional | The nextCursor value from the previous page. Leave it out to get the first page. From 1 to 512 characters. |
| `search` | string | Optional | Return only the videos whose title contains this text, ignoring case. From 1 to 200 characters. |

## Request

List your videos.

```bash title="curl"
curl "https://api.gpt-video.com/v1/assets" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY"
```

```ts title="TypeScript"
const res = await fetch("https://api.gpt-video.com/v1/assets", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GPT_VIDEO_API_KEY}`,
  },
});
const data = await res.json();
console.log(data);
```

```python title="Python"
import os

import requests

r = requests.get(
    "https://api.gpt-video.com/v1/assets",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
    },
)
data = r.json()
print(data)
```

```json title="MCP (Full)"
{
  "method": "tools/call",
  "params": {
    "name": "list_assets",
    "arguments": {}
  }
}
```

## Response

A successful call answers HTTP 200.

### Fields to check

| Name | Type | Description |
| --- | --- | --- |
| `data[].id` | string | The asset id. It starts with ast_. |
| `hasMore` | boolean | true when there are more items after this page. |
| `nextCursor` | string or null | Send it as cursor to get the next page. It is null on the last page. |

### Response example

```json title="HTTP 200"
{
  "data": [
    {
      "id": "ast_8e21b0d94c6f4a17b358",
      "kind": "video",
      "title": "Product demo",
      "filename": "demo.mp4",
      "origin": "upload",
      "mimeType": "video/mp4",
      "sizeBytes": 50331648,
      "durationSec": 120,
      "width": 1920,
      "height": 1080,
      "fps": 30,
      "hasAudio": true,
      "createdAt": "2026-09-01T09:05:00.000Z",
      "deletesAt": "2026-09-08T09:05:00.000Z"
    },
    {
      "id": "ast_3f9a1c7e5b2d4086a1c4",
      "kind": "video",
      "title": "Interview with a founder",
      "filename": "interview.mp4",
      "origin": "upload",
      "mimeType": "video/mp4",
      "sizeBytes": 734003200,
      "durationSec": 1800,
      "width": 1920,
      "height": 1080,
      "fps": 30,
      "hasAudio": true,
      "createdAt": "2026-09-01T09:00:00.000Z",
      "deletesAt": null
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

**All response fields**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of objects | Required | The items of this page. |
| `data[].id` | string | Required | The asset id. It starts with ast_. |
| `data[].kind` | string | Required | One of `video`, `audio`, `image`, `font`, `other`. |
| `data[].title` | string | Required |   |
| `data[].filename` | string or null | Required | The name of the file as it was uploaded, when there was one. |
| `data[].origin` | string | Required | upload was sent by you, link was imported from a link, converted is a playable copy made for the analysis, export is the file of an export, voice is the audio of a voiceover, separated is the audio an audio separation kept. One of `upload`, `link`, `converted`, `export`, `voice`, `separated`. |
| `data[].mimeType` | string | Required |   |
| `data[].sizeBytes` | integer | Required |   |
| `data[].durationSec` | number or null | Required |   |
| `data[].width` | integer or null | Required | The width as the video is shown, rotation applied. |
| `data[].height` | integer or null | Required | The height as the video is shown, rotation applied. |
| `data[].fps` | number or null | Required |   |
| `data[].hasAudio` | boolean or null | Required |   |
| `data[].createdAt` | string | Required | An ISO 8601 time in UTC. |
| `data[].deletesAt` | string or null | Required | The first time the file may be deleted to free space: files are kept for a limited time. null when nothing deletes it. |
| `hasMore` | boolean | Required | true when there are more items after this page. |
| `nextCursor` | string or null | Required | Send it as cursor to get the next page. It is null on the last page. |

**More examples**

#### List your videos one at a time

`GET /v1/assets?limit=1`

```json title="HTTP 200"
{
  "data": [
    {
      "id": "ast_8e21b0d94c6f4a17b358",
      "kind": "video",
      "title": "Product demo",
      "filename": "demo.mp4",
      "origin": "upload",
      "mimeType": "video/mp4",
      "sizeBytes": 50331648,
      "durationSec": 120,
      "width": 1920,
      "height": 1080,
      "fps": 30,
      "hasAudio": true,
      "createdAt": "2026-09-01T09:05:00.000Z",
      "deletesAt": "2026-09-08T09:05:00.000Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJrIjp7ImNyZWF0ZWRBdCI6IjIwMjYtMDktMDFUMDk6MDU6MDAuMDAwWiIsImlkIjoiYXN0XzhlMjFiMGQ5NGM2ZjRhMTdiMzU4In0sInYiOjF9"
}
```

#### Get the next page

`GET /v1/assets?limit=1&cursor=eyJrIjp7ImNyZWF0ZWRBdCI6IjIwMjYtMDktMDFUMDk6MDU6MDAuMDAwWiIsImlkIjoiYXN0XzhlMjFiMGQ5NGM2ZjRhMTdiMzU4In0sInYiOjF9`

```json title="HTTP 200"
{
  "data": [
    {
      "id": "ast_3f9a1c7e5b2d4086a1c4",
      "kind": "video",
      "title": "Interview with a founder",
      "filename": "interview.mp4",
      "origin": "upload",
      "mimeType": "video/mp4",
      "sizeBytes": 734003200,
      "durationSec": 1800,
      "width": 1920,
      "height": 1080,
      "fps": 30,
      "hasAudio": true,
      "createdAt": "2026-09-01T09:00:00.000Z",
      "deletesAt": null
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

#### Find a video by its title

`GET /v1/assets?search=demo`

```json title="HTTP 200"
{
  "data": [
    {
      "id": "ast_8e21b0d94c6f4a17b358",
      "kind": "video",
      "title": "Product demo",
      "filename": "demo.mp4",
      "origin": "upload",
      "mimeType": "video/mp4",
      "sizeBytes": 50331648,
      "durationSec": 120,
      "width": 1920,
      "height": 1080,
      "fps": 30,
      "hasAudio": true,
      "createdAt": "2026-09-01T09:05:00.000Z",
      "deletesAt": "2026-09-08T09:05:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

## Errors

Every call can also answer these errors. [`VALIDATION_FAILED`](/developers/errors.md#VALIDATION_FAILED), [`UNKNOWN_PARAMETER`](/developers/errors.md#UNKNOWN_PARAMETER), [`UNAUTHORIZED`](/developers/errors.md#UNAUTHORIZED), [`SCOPE_MISSING`](/developers/errors.md#SCOPE_MISSING), [`RATE_LIMITED`](/developers/errors.md#RATE_LIMITED), [`INTERNAL`](/developers/errors.md#INTERNAL), [`UNAVAILABLE`](/developers/errors.md#UNAVAILABLE).

## Cost

No credits are used.

## Related operations

- [`get_asset`](/developers/api/get-asset.md) (`GET /v1/assets/{assetId}`) Get an asset
- [`get_transcript`](/developers/api/get-transcript.md) (`GET /v1/assets/{assetId}/transcript`) Get the transcript of a video
- [`create_project`](/developers/api/create-project.md) (`POST /v1/projects`) Create a project
- [`separate_audio`](/developers/api/separate-audio.md) (`POST /v1/audio-separations`) Separate the voices of a video

## Questions

### Why is an export not in this list?

The list holds only the videos that came from you. The file of an export is read with get_asset (`GET /v1/assets/{assetId}`), by the id its export gives.

### Does a video I uploaded in the app show up here?

Yes. Videos uploaded in the GPT-Video app and through the API are the same list. The background clips of the app's library are the one exception: they are not sources, and they are not listed.