List Videos

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

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`);

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')

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

GET

video

list

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

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`);

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')

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

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
scenes: Scenes videos
add_captions: Add Captions videos
extend_video: Extend Video
remove_background: Remove background videos
tiktok_slideshow: TikTok slideshows

string

Filter by status:

draft: Draft videos
processing: Currently processing
completed: Completed videos
failed: Failed videos

number

default:"50"

Number of results (max: 100)

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"

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`);

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')

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

draft

Video is created but not yet processing

processing

Video is currently being generated (usually 2-5 minutes)

completed

Video is ready! Download URL is available

failed

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

By Status
By Type
Combined

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

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

# 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"

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

Show child attributes

Getting Started

Resources

Videos

Images

Templates

Social Accounts

Scheduling

Overview

Query Parameters

Video Status

Use Cases

Dashboard View

Status Monitoring

Analytics

Bulk Operations

Filtering Examples

Create Video

List Templates

Authorizations

Query Parameters

Response

​Overview

​Query Parameters

​Video Status

​Pagination

​Use Cases

Dashboard View

Status Monitoring

Analytics

Bulk Operations

​Filtering Examples

​Related Endpoints

Create Video

List Templates

Authorizations

Query Parameters

Response

Overview

Query Parameters

Video Status

Pagination

Use Cases

Filtering Examples

Related Endpoints