> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inworld.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List videos

> List your workspace's video jobs, newest first

List your workspace's video jobs, newest first, in pages of up to 100. While `has_more` is `true`, get the next page by passing the response's `last_id` as `after`.

Deleted jobs, and completed jobs whose video has expired (past `expires_at`), are not listed. Failed and cancelled jobs remain listed until automatic cleanup removes them. They become eligible for removal 7 days after they end, but cleanup can happen later.

The list is not permanent history. Save job ids and final results in your own database if you need them after expiry or removal.

Each entry includes the job's status and parameters but no download link. [Retrieve](https://docs.inworld.ai/api-reference/videoAPI/retrieve-video.md) a completed job to get its download link.

## API reference

**Endpoint:** `GET https://api.inworld.ai/v1/videos`

### Authorization

- `Authorization` (string; required) — Your [authentication](https://docs.inworld.ai/api-reference/introduction.md) credentials. For Basic authentication, populate `Basic $INWORLD_API_KEY`.

### Query parameters

- `limit` (integer; default: 20) — How many jobs to return, from 1 to 100.
- `after` (string) — A job id from a previous page, usually its `last_id`. Returns the jobs created before that one.

### Response

Status: `200`. Content type: `application/json`.

- `object` (enum<string>; options: "list")
- `data` (object[]) — Jobs, newest first, without `output`.
  - `id` (string; required) — The job id.
  - `object` (enum<string>; required; options: "video")
  - `model` (string; required)
  - `status` (enum<string>; required; options: "queued", "in_progress", "completed", "failed", "cancelled") — `queued`: accepted; waiting for or being submitted for generation, so cancellation may already be unavailable. `in_progress`: generating. `completed`: generation succeeded; download available until `expires_at`. `failed`: see `error`. `cancelled`: cancelled before generation started. The last three are terminal.
  - `created_at` (integer; required) — When the job was created, in Unix seconds.
  - `completed_at` (integer) — When the video finished, in Unix seconds. Present once `status` is `completed`.
  - `expires_at` (integer) — Until when the video can be downloaded, in Unix seconds: 7 days after it finished. After it, the job is no longer listed. Present only when `status` is `completed`.
  - `seconds` (integer; required) — The requested clip length, with the model's default filled in.
  - `resolution` (string; required) — The requested resolution, with the model's default filled in.
  - `aspect_ratio` (string; required) — The requested aspect ratio, with the model's default filled in. `adaptive` for a job with `frame_images`, whose video takes the first frame's shape.
  - `operation` (string) — The job's [long-running operation](https://google.aip.dev/151). Poll it with `GET https://api.inworld.ai/lro/v1alpha/{operation}` as an alternative to retrieving the job. The operation reports progress and the outcome but never the download link. See [Poll the operation instead](https://docs.inworld.ai/router/video-generation.md#poll-the-operation-instead).
  - `error` (object) — Why the job failed. Present only when `status` is `failed`.
    - `code` (enum<string>; options: "content_filtered", "invalid_request", "generation_failed", "generation_timeout") — `content_filtered`: the prompt or the generated video was blocked by the model provider's content policy. `invalid_request`: the model provider rejected the request. `generation_failed`: generation failed for another reason. `generation_timeout`: generation did not finish in time.
    - `message` (string)
  - `output` (object) — The finished video. Returned only by [Retrieve video](https://docs.inworld.ai/api-reference/videoAPI/retrieve-video.md), only while `status` is `completed` and before `expires_at`.
    - `videos` (object[])
      - `index` (integer)
      - `content_type` (string)
      - `bytes` (integer) — File size in bytes.
      - `url` (string) — A signed HTTPS link to the MP4. Anyone with the link can download the file until `url_expires_at`, so treat it like a secret.
      - `url_expires_at` (integer) — When `url` stops working, in Unix seconds: up to an hour after the request, and never after the job's `expires_at`.
- `has_more` (boolean) — Whether older jobs remain. Pass `last_id` as `after` to get them.
- `first_id` (string) — The id of the first job on this page. Absent on an empty page.
- `last_id` (string) — The id of the last job on this page. Absent on an empty page.

### Response examples

#### 200: default_response

```json
{
  "object": "list",
  "data": [
    {
      "id": "video_8f14e45fceea167a5a36dedd4bea2543",
      "object": "video",
      "model": "alibaba/wan-3.0",
      "status": "queued",
      "created_at": 0,
      "completed_at": 0,
      "expires_at": 0,
      "seconds": 0,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "operation": "workspaces/my-workspace/videoGenerationJobs/video_8f14e45fceea167a5a36dedd4bea2543/operations/1790000000000-a1b2c3",
      "error": {
        "code": "content_filtered",
        "message": "The request or its output was blocked by the provider's content policy."
      },
      "output": {
        "videos": [
          {
            "index": 0,
            "content_type": "video/mp4",
            "bytes": 0,
            "url": "string",
            "url_expires_at": 0
          }
        ]
      }
    }
  ],
  "has_more": true,
  "first_id": "string",
  "last_id": "string"
}
```

#### 400: default_response

```json
{
  "error": {
    "message": "seconds must be an integer from 2 to 30",
    "type": "invalid_request_error",
    "code": "string",
    "param": "seconds"
  }
}
```

#### 401: default_response

```json
"Unauthorized"
```

#### 403: default_response

```json
"Forbidden"
```

#### 429: default_response

```json
"Rate limit exceeded"
```

#### 500: default_response

```json
{
  "error": {
    "message": "seconds must be an integer from 2 to 30",
    "type": "invalid_request_error",
    "code": "string",
    "param": "seconds"
  }
}
```

#### 503: default_response

```json
{
  "error": {
    "message": "seconds must be an integer from 2 to 30",
    "type": "invalid_request_error",
    "code": "string",
    "param": "seconds"
  }
}
```

### Code examples

#### cURL

```bash
curl 'https://api.inworld.ai/v1/videos?limit=20' \
  -H "Authorization: Basic $INWORLD_API_KEY"
```

#### Python

```python
import requests

url = "https://api.inworld.ai/v1/videos"
headers = {
  "Authorization": "<api_key>"
}

response = requests.request("GET", url, headers=headers)

print(response.text)
```

#### JavaScript

```javascript
const options = {method: 'GET', headers: {"Authorization":"<api_key>"}};

fetch('https://api.inworld.ai/v1/videos', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
```
