List Videos

GET /v1/videos

List all videos in your workspace with pagination and optional status filtering.

Query parameters

Parameter	Type	Required	Default	Description
page	integer	No	1	Page number (minimum 1)
limit	integer	No	20	Results per page (1–100)
status	string	No	—	Filter by status: draft, in_progress, or completed
projectId	string	No	—	Return only videos in the given project folder. 404 if the folder doesn't belong to the workspace.
uncategorized	boolean	No	—	If true, return only videos with no project folder. Overrides projectId.

Example

curl "https://api.vidocu.ai/v1/videos?page=1&limit=10&status=completed" \
  -H "Authorization: Bearer vdo_live_your_key_here"

Response 200 OK

{
  "videos": [
    {
      "id": "vid_1708300000000_abc1234",
      "projectId": "0f7c1d8a-2c4b-4a9c-9f2a-1b8a3a5e0c11",
      "name": "Product Demo Q1",
      "status": "completed",
      "videoUrl": "https://storage.vidocu.ai/...",
      "thumbnailUrl": "https://storage.vidocu.ai/...",
      "videoDuration": 120.5,
      "language": "en",
      "exportedVideoUrl": "https://storage.vidocu.ai/...",
      "exportedSrtUrl": "https://storage.vidocu.ai/...",
      "exportedVoiceoverUrl": "https://storage.vidocu.ai/...",
      "exportedAt": "2024-02-19T10:30:00.000Z",
      "createdAt": "2024-02-18T14:00:00.000Z",
      "updatedAt": "2024-02-19T10:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "limit": 10,
    "totalPages": 5
  }
}

Video object fields

Field	Type	Description
id	string	Unique video ID
projectId	string | null	Parent project folder ID (null when uncategorized)
name	string	Display name
status	string	draft, in_progress, or completed
videoUrl	string	Source video URL
thumbnailUrl	string | null	Generated thumbnail URL
videoDuration	number | null	Duration in seconds
language	string | null	Detected language code
exportedVideoUrl	string | null	Exported video URL (after export)
exportedSrtUrl	string | null	Exported SRT file URL (after export)
exportedVoiceoverUrl	string | null	Combined voiceover MP3 URL (after export, if voiceover was generated)
exportedAt	string | null	Export timestamp
createdAt	string	Creation timestamp
updatedAt	string	Last update timestamp

Results are sorted by updatedAt descending (most recent first).

Errors

Status	Code	Cause
400	validation_error	Invalid query parameter values
401	authentication_error	Invalid or missing API key