> ## 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

Returns your workspace's video jobs, newest first, in pages of up to 100. To get the next page, pass the response's `last_id` as `after` while `has_more` is `true`.

List entries carry each 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 one.

## 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. 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.
  - `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));
```