> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hooked.so/llms.txt
> Use this file to discover all available pages before exploring further.
# List Videos
> Get all your created videos (excludes templates)
## Overview
This endpoint returns all videos (projects) you've created, excluding templates. Use this to retrieve your video history, check statuses, and manage your content.
This endpoint only returns regular videos. For templates, use [List Templates](/api-reference/template/list).
### Query Parameters
Filter by video type:
* `class`: Educational videos
* `ugc_ads`: UGC advertising
* `ugc_video`: Talking avatar videos
* `script_to_video`: Script to Videos
* `prompt_to_video`: Prompt to Videos
* `hook_demo`: Hook + Demo
* `product_ads`: Product Ads
* `scenes`: Scenes videos
* `add_captions`: Add Captions videos
* `extend_video`: Extend Video
* `remove_background`: Remove background videos
* `tiktok_slideshow`: TikTok slideshows
Filter by status:
* `draft`: Draft videos
* `processing`: Currently processing
* `completed`: Completed videos
* `failed`: Failed videos
Number of results (max: 100)
Pagination offset
```bash cURL theme={null}
curl -X GET "https://api.hooked.so/v1/video/list?status=completed&limit=10" \
-H "x-api-key: your_api_key_here"
```
```javascript Node.js theme={null}
const response = await fetch('https://api.hooked.so/v1/video/list?status=completed', {
headers: { 'x-api-key': 'your_api_key_here' }
});
const { videos } = await response.json().data;
console.log(`Found ${videos.length} completed videos`);
```
```python Python theme={null}
import requests
response = requests.get(
'https://api.hooked.so/v1/video/list',
params={'status': 'completed', 'limit': 10},
headers={'x-api-key': 'your_api_key_here'}
)
videos = response.json()['data']['videos']
print(f'Found {len(videos)} videos')
```
```json Response theme={null}
{
"success": true,
"data": {
"videos": [
{
"id": "vid_abc123",
"name": "Product Tutorial",
"status": "COMPLETED",
"url": "https://signed-s3-url.example.com/videos/vid_abc123.mp4",
"durationInFrames": 6250,
"projectId": "proj_class_001",
"thumbnail": "https://cdn.hooked.so/thumbnails/vid_abc123.jpg",
"size": 15728640,
"progress": 100,
"message": "Video ready",
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-15T10:05:00Z"
},
{
"id": "vid_def456",
"name": "Social Media Clip",
"status": "COMPLETED",
"url": "https://signed-s3-url.example.com/videos/vid_def456.mp4",
"durationInFrames": 3750,
"projectId": "proj_ugc_ads_002",
"thumbnail": "https://cdn.hooked.so/thumbnails/vid_def456.jpg",
"size": 9437184,
"progress": 100,
"message": "Video ready",
"createdAt": "2024-01-15T11:00:00Z",
"updatedAt": "2024-01-15T11:03:00Z"
}
],
"total": 2,
"limit": 50,
"offset": 0
}
}
```
## Video Status
Each video has one of these statuses:
Video is created but not yet processing
Video is currently being generated (usually 2-5 minutes)
Video is ready! Download URL is available
Video generation failed - check the `message` field for details
## Pagination
For large video lists, use pagination:
```javascript Pagination Example theme={null}
async function getAllVideos() {
const allVideos = [];
let offset = 0;
const limit = 100;
while (true) {
const response = await fetch(
`https://api.hooked.so/v1/video/list?limit=${limit}&offset=${offset}`,
{ headers: { 'x-api-key': API_KEY } }
);
const { videos, total } = await response.json().data;
allVideos.push(...videos);
if (allVideos.length >= total) break;
offset += limit;
}
return allVideos;
}
```
## Use Cases
Build a video management dashboard
Track video processing status
Analyze video creation trends
Manage multiple videos at once
## Filtering Examples
```bash theme={null}
# Get all completed videos
curl "https://api.hooked.so/v1/video/list?status=completed" \
-H "x-api-key: your_api_key_here"
```
```bash theme={null}
# Get all educational videos
curl "https://api.hooked.so/v1/video/list?type=class" \
-H "x-api-key: your_api_key_here"
```
```bash theme={null}
# Get completed UGC ads
curl "https://api.hooked.so/v1/video/list?type=ugc_ads&status=completed&limit=20" \
-H "x-api-key: your_api_key_here"
```
## Related Endpoints
Create a new video
View your templates
## OpenAPI
````yaml GET /v1/video/list
openapi: 3.0.0
info:
title: Hooked API
version: 1.0.0
description: AI Video Generation API
servers:
- url: https://api.hooked.so
security:
- ApiKeyAuth: []
paths:
/v1/video/list:
get:
tags: []
summary: List Videos from Projects
description: >-
Get all videos from your projects. Extracts videos from projects
(excludes templates) and returns them with video details including
duration, status, and download URLs.
operationId: listVideos
parameters:
- name: type
in: query
description: >-
Filter by project/video type. Use 'all' to get videos from all
project types.
required: false
schema:
type: string
enum:
- class
- ugc_ads
- ugc_video
- script_to_video
- hook_demo
- tiktok_slideshow
- all
default: all
- name: status
in: query
description: Filter by video status
required: false
schema:
type: string
enum:
- draft
- processing
- completed
- failed
- name: limit
in: query
description: >-
Maximum number of projects to fetch (results will include all videos
from those projects)
required: false
schema:
type: integer
default: 50
maximum: 100
- name: offset
in: query
description: Pagination offset for projects
required: false
schema:
type: integer
default: 0
responses:
'200':
description: Videos retrieved successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
data:
type: object
properties:
videos:
type: array
description: List of videos from projects
items:
type: object
properties:
id:
type: string
description: Unique video identifier
name:
type: string
description: Video name/title
status:
type: string
enum:
- STARTED
- COMPLETED
- FAILED
description: Current video processing status
url:
type: string
description: >-
Signed URL to download the video (only available
when status is COMPLETED)
durationInFrames:
type: integer
description: Duration of the video in frames (at 25fps)
projectId:
type: string
description: ID of the project this video belongs to
thumbnail:
type: string
nullable: true
description: URL to video thumbnail image
size:
type: integer
description: Video file size in bytes
progress:
type: integer
minimum: 0
maximum: 100
description: Processing progress percentage (0-100)
message:
type: string
nullable: true
description: Status message or error details
createdAt:
type: string
format: date-time
description: Video creation timestamp
updatedAt:
type: string
format: date-time
description: Last update timestamp
total:
type: integer
description: Total number of videos returned
limit:
type: integer
description: Limit parameter used
offset:
type: integer
description: Offset parameter used
security:
- ApiKeyAuth: []
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````