Skip to main content
GET
/
v1
/
video
/
list
curl -X GET "https://api.hooked.so/v1/video/list?status=completed&limit=10" \
  -H "x-api-key: your_api_key_here"

{
  "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
  }
}

​
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.

​
Query Parameters

​
type
string
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
​
status
string
Filter by status:
  • draft: Draft videos
  • processing: Currently processing
  • completed: Completed videos
  • failed: Failed videos
​
limit
number
default:"50"
Number of results (max: 100)
​
offset
number
default:"0"
Pagination offset
curl -X GET "https://api.hooked.so/v1/video/list?status=completed&limit=10" \
  -H "x-api-key: your_api_key_here"

{
  "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:
Pagination Example
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

Dashboard View

Build a video management dashboard

Status Monitoring

Track video processing status

Analytics

Analyze video creation trends

Bulk Operations

Manage multiple videos at once

​
Filtering Examples

# Get all completed videos
curl "https://api.hooked.so/v1/video/list?status=completed" \
  -H "x-api-key: your_api_key_here"

Create Video

Create a new video

List Templates

View your templates

Authorizations

​
x-api-key
string
header
required

Query Parameters

​
type
enum<string>
default:all

Filter by project/video type. Use 'all' to get videos from all project types.

Available options:
class,
ugc_ads,
ugc_video,
script_to_video,
hook_demo,
tiktok_slideshow,
all
​
status
enum<string>

Filter by video status

Available options:
draft,
processing,
completed,
failed
​
limit
integer
default:50

Maximum number of projects to fetch (results will include all videos from those projects)

Required range: x <= 100
​
offset
integer
default:0

Pagination offset for projects

Response

200 - application/json

Videos retrieved successfully

​
success
boolean
Example:

true

​
data
object