---
title: "List your videos"
method: GET
path: "/videos"
tags: ["Videos"]
---

# List your videos

`GET /videos`

Returns all videos for your organization, sorted newest first. Use this to browse your video library, check generation statuses, or find a video to export/publish.

**Polling for generation status:** After calling `POST /generate`, poll this endpoint or `GET /videos/{id}` until `status` changes from `processing` to `completed` or `failed`. Typical generation takes 1-3 minutes.

## Query parameters

- `limit` number — Maximum number of videos to return per page. Default: 50, max: 100.
- `cursor` string, uuid — Pagination cursor: the `id` of the LAST video from the previous page. Returns videos older than that one. Omit for the first page. An empty array means there are no more videos.

## Response `200`

OK

- object[] — List of videos sorted newest first.
  - `id` string, uuid, required — Unique video identifier. Use this to fetch details, export, or publish.
  - `title` string, required — Video title. Auto-generated from the script if not provided during creation.
  - `status` 'pending' | 'processing' | 'completed' | 'failed', required — Current generation status. - `pending`: Video is queued for generation. - `processing`: Video is being generated (audio, images, composition). - `completed`: Video is ready to export or publish. - `failed`: Generation failed. Check `errorMessage` for details.
  - `mediaType` 'images' | 'video' | 'stock' | 'avatar' | 'byov', required — Type of visuals used in the video. - `images`: AI-generated images with Ken Burns animation (most popular). - `video`: AI-generated video clips. - `stock`: Real stock footage matched to the script. - `avatar`: Talking-head avatar video. - `byov`: Bring-your-own video clips.
  - `durationSeconds` integer, required — Video duration in seconds. Determined by the narration length.
  - `aspectRatio` string, nullable, required — Video aspect ratio. - `9:16`: Vertical (YouTube Shorts, TikTok, Reels). - `16:9`: Horizontal (standard YouTube). - `1:1`: Square (Instagram feed).
  - `imageQuality` string, nullable, required — Image generation quality tier used. Only present for `images` media type. - `basic`: Fast, low cost. - `good`: Better detail. - `premium`: High detail. - `max`: Maximum quality.
  - `imageStyleId` string, nullable, required — Visual art style used for image generation (e.g. `photorealistic`, `anime`, `cinematic`). Only present for `images` media type.
  - `exportStatus` 'pending' | 'processing' | 'completed' | 'failed', nullable, required — Status of the latest MP4 export. `null` if the video has never been exported. - `pending`: Export is queued. - `processing`: MP4 is being rendered. - `completed`: Ready to download via `GET /exports/download?videoId={id}`. - `failed`: Export rendering failed. Try exporting again.
  - `errorMessage` string, nullable, required — Human-readable error message if `status` is `failed`. `null` otherwise.
  - `createdAt` string, date-time, required — When the video was created (ISO 8601).
  - `updatedAt` string, date-time, required — When the video was last updated (ISO 8601).

## Other responses

- `401` — 401
- `402` — 402
- `403` — 403

---

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