---
title: "Paginated list of Videos"
method: GET
path: "/videos"
---

# Paginated list of Videos

`GET /videos`

Returns a paginated array of Videos

## Query parameters

- `page` integer
- `limit` integer
- `nameSearchQuery` string
- `avatarId` string
- `voiceId` string
- `extrasFilter` string

## Response `200`

A paginated list of Videos

- object
  - `totalItems` integer — Total number of videos available
  - `totalPages` integer — Total number of pages
  - `currentPage` integer — Current page number
  - `itemsPerPage` integer — Number of items per page
  - `videos` Video[]
    - `id` string, uuid
    - `name` string
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `status` string — Can be either `IDLE`, `GENERATING_AUDIO`, `GENERATING_VIDEO`, `DONE` or `FAILED`.
    - `duration` number, nullable — Total video duration in seconds. `null` when audio hasn't been generated yet.
    - `moments` object[] — An array of Moment items, each representing a portion of the complete video.
      - `transcript` string — A portion of the complete transcript. Current limit: 500 characters.
      - `avatarId` string — The id of the avatar to be used for this moment.
      - `voiceId` string — The id of the voice to be used for this moment.
      - `audioUrl` string — The audio that will be used for the video rendering. Automatically generated from the transcript when not provided. Current limit: 40 seconds.
      - `videoUrl` string — The url of the avatar rendering video for this moment.
      - `gestureSlug` string — The slug identifier of the gesture to be used for this moment.
      - `zoom` object — Current zoom effect applied to the avatar. Present only when a non-default zoom is set.
      - `broll` object — B-roll information for this moment.
        - `zoom` object — Current zoom effect applied to the B-roll. Present only when a non-default zoom is set.
    - `videoUrl` string — The url of the final avatar rendering video, containing all the moments merged.
    - `videoUrlSubtitled` string — The url of the final avatar rendering video with subtitles. Only available if subtitles are enabled.
    - `previewUrl` string — Url to the embedable preview of the video. Can be watched from web browsers or integrated in other websites before launching the generation. For embedable mode, add ?embed=true to the url.
    - `aspectRatio` '16:9' | '9:16' — The aspect ratio of the video output: 16:9 or 9:16.
    - `subtitles` object — Subtitles settings for the video
      - `enable` boolean
    - `extras` object — A dictionary of custom key-value pairs to extend the video metadata. Maximum of 5 key-value pairs of 256 characters allowed.

## Other responses

- `400` — Unexpected error

## Changes

- **2026-04-20** `166231bcfa85` — 1 info
  - added the optional property `videos/items/duration` to the response with the `200` status
- **2026-04-16** `3e376c91df56` — 1 warning
  - removed the optional property `videos/items/duration` from the response with the `200` status
- **2026-04-16** `ac2be3dc5af8` — 1 info
  - added the optional property `videos/items/duration` to the response with the `200` status
- **2026-03-31** `23f7e6a6f6ce` — 2 info
  - added the optional property `videos/items/moments/items/broll` to the response with the `200` status
  - added the optional property `videos/items/moments/items/zoom` to the response with the `200` status
- **2026-01-13** `6345ae35047e` — 2 info
  - added the optional property `videos/items/aspectRatio` to the response with the `200` status
  - added the optional property `videos/items/previewUrl` to the response with the `200` status

[Change history](https://skmtc.dev/argildotai/apis/argil-api/changes/videos/get.md)

---

[API](https://skmtc.dev/argildotai/apis/argil-api.md) · [All operations](https://skmtc.dev/argildotai/apis/argil-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/argildotai/argil-api/revisions/f3d0315da0f0/schema)