curl "https://api.hooked.so/v1/video/list?status=COMPLETED&limit=20" \
-H "x-api-key: your_api_key_here"
const params = new URLSearchParams({ status: "COMPLETED", limit: "20" });
const response = await fetch(`https://api.hooked.so/v1/video/list?${params}`, {
headers: { "x-api-key": process.env.HOOKED_API_KEY },
});
const { data } = await response.json();
console.log(`${data.videos.length} of ${data.total} completed videos`);
import os
import requests
response = requests.get(
"https://api.hooked.so/v1/video/list",
params={"status": "COMPLETED", "limit": 20},
headers={"x-api-key": os.environ["HOOKED_API_KEY"]},
)
data = response.json()["data"]
print(f"{len(data['videos'])} of {data['total']} completed videos")
{
"success": true,
"message": "Videos fetched successfully",
"data": {
"videos": [
{
"id": "cm4x9n7q20003ab12xy98zt10",
"name": "Morning routine tips",
"projectId": "cm4x9k2p10001ab12cd34ef56",
"projectType": "script_to_video",
"status": "COMPLETED",
"progress": 100,
"message": "Video ready",
"url": "https://files.hooked.so/team/videos/cm4x9n7q20003ab12xy98zt10.mp4?X-Amz-Signature=...",
"thumbnail": "https://files.hooked.so/team/thumbnails/cm4x9n7q20003ab12xy98zt10.jpg?X-Amz-Signature=...",
"durationInFrames": 1125,
"durationInSeconds": 45,
"size": 18874368,
"createdAt": "2026-10-01T09:15:58.000Z",
"updatedAt": "2026-10-01T09:16:41.000Z"
}
],
"total": 37,
"limit": 20,
"offset": 0
}
}
{
"success": false,
"message": "status: Must be one of STARTED, COMPLETED, FAILED"
}
{
"code": "not_authenticated",
"message": "Not authenticated",
"errorCode": "NOT_AUTHENTICATED",
"details": { "x-api-key": "Header not provided or API Key invalid" }
}
{
"code": "entitlement_required",
"error": "entitlement_required",
"message": "This endpoint requires the \"app\" product.",
"product": "app"
}
Videos
List Videos
List the rendered videos of your team, newest first
GET
/
v1
/
video
/
list
curl "https://api.hooked.so/v1/video/list?status=COMPLETED&limit=20" \
-H "x-api-key: your_api_key_here"
const params = new URLSearchParams({ status: "COMPLETED", limit: "20" });
const response = await fetch(`https://api.hooked.so/v1/video/list?${params}`, {
headers: { "x-api-key": process.env.HOOKED_API_KEY },
});
const { data } = await response.json();
console.log(`${data.videos.length} of ${data.total} completed videos`);
import os
import requests
response = requests.get(
"https://api.hooked.so/v1/video/list",
params={"status": "COMPLETED", "limit": 20},
headers={"x-api-key": os.environ["HOOKED_API_KEY"]},
)
data = response.json()["data"]
print(f"{len(data['videos'])} of {data['total']} completed videos")
{
"success": true,
"message": "Videos fetched successfully",
"data": {
"videos": [
{
"id": "cm4x9n7q20003ab12xy98zt10",
"name": "Morning routine tips",
"projectId": "cm4x9k2p10001ab12cd34ef56",
"projectType": "script_to_video",
"status": "COMPLETED",
"progress": 100,
"message": "Video ready",
"url": "https://files.hooked.so/team/videos/cm4x9n7q20003ab12xy98zt10.mp4?X-Amz-Signature=...",
"thumbnail": "https://files.hooked.so/team/thumbnails/cm4x9n7q20003ab12xy98zt10.jpg?X-Amz-Signature=...",
"durationInFrames": 1125,
"durationInSeconds": 45,
"size": 18874368,
"createdAt": "2026-10-01T09:15:58.000Z",
"updatedAt": "2026-10-01T09:16:41.000Z"
}
],
"total": 37,
"limit": 20,
"offset": 0
}
}
{
"success": false,
"message": "status: Must be one of STARTED, COMPLETED, FAILED"
}
{
"code": "not_authenticated",
"message": "Not authenticated",
"errorCode": "NOT_AUTHENTICATED",
"details": { "x-api-key": "Header not provided or API Key invalid" }
}
{
"code": "entitlement_required",
"error": "entitlement_required",
"message": "This endpoint requires the \"app\" product.",
"product": "app"
}
Overview
Returns your team’s rendered videos, newest first, with the total count for paging. A project appears here only once its render has started. To follow a project that is still generating, or one that failed before rendering, use Get Project with theprojectId from the create response.
curl "https://api.hooked.so/v1/video/list?status=COMPLETED&limit=20" \
-H "x-api-key: your_api_key_here"
const params = new URLSearchParams({ status: "COMPLETED", limit: "20" });
const response = await fetch(`https://api.hooked.so/v1/video/list?${params}`, {
headers: { "x-api-key": process.env.HOOKED_API_KEY },
});
const { data } = await response.json();
console.log(`${data.videos.length} of ${data.total} completed videos`);
import os
import requests
response = requests.get(
"https://api.hooked.so/v1/video/list",
params={"status": "COMPLETED", "limit": 20},
headers={"x-api-key": os.environ["HOOKED_API_KEY"]},
)
data = response.json()["data"]
print(f"{len(data['videos'])} of {data['total']} completed videos")
{
"success": true,
"message": "Videos fetched successfully",
"data": {
"videos": [
{
"id": "cm4x9n7q20003ab12xy98zt10",
"name": "Morning routine tips",
"projectId": "cm4x9k2p10001ab12cd34ef56",
"projectType": "script_to_video",
"status": "COMPLETED",
"progress": 100,
"message": "Video ready",
"url": "https://files.hooked.so/team/videos/cm4x9n7q20003ab12xy98zt10.mp4?X-Amz-Signature=...",
"thumbnail": "https://files.hooked.so/team/thumbnails/cm4x9n7q20003ab12xy98zt10.jpg?X-Amz-Signature=...",
"durationInFrames": 1125,
"durationInSeconds": 45,
"size": 18874368,
"createdAt": "2026-10-01T09:15:58.000Z",
"updatedAt": "2026-10-01T09:16:41.000Z"
}
],
"total": 37,
"limit": 20,
"offset": 0
}
}
{
"success": false,
"message": "status: Must be one of STARTED, COMPLETED, FAILED"
}
{
"code": "not_authenticated",
"message": "Not authenticated",
"errorCode": "NOT_AUTHENTICATED",
"details": { "x-api-key": "Header not provided or API Key invalid" }
}
{
"code": "entitlement_required",
"error": "entitlement_required",
"message": "This endpoint requires the \"app\" product.",
"product": "app"
}
Paging through every video
total counts every video that matches the filters; you are done when offset + limit >= total. limit is 50 by default and at most 100.
async function listAllVideos() {
const all = [];
for (let offset = 0; ; offset += 100) {
const response = await fetch(
`https://api.hooked.so/v1/video/list?limit=100&offset=${offset}`,
{ headers: { "x-api-key": process.env.HOOKED_API_KEY } }
);
const { data } = await response.json();
all.push(...data.videos);
if (offset + data.limit >= data.total) return all;
}
}
Errors
| Status | Message | Cause |
|---|---|---|
| 400 | type: Unknown project type "..." | type is not a project type or all. |
| 400 | status: Must be one of STARTED, COMPLETED, FAILED | Unknown status. |
| 401 | code: "not_authenticated" | Missing or invalid x-api-key. |
| 403 | code: "entitlement_required" | Your team does not have the Hooked app product. |
| 500 | Failed to fetch videos | Retry the request. |
Related
Get Video Details
One video by ID
Get Project
Follow a project before its render starts
Authorizations
Query Parameters
Only videos of this project type, or all. Any other value answers 400. API formats: script_to_video, prompt_to_video, ugc_ads, ugc_video (Talking Avatar), hook_demo, scenes, tiktok_slideshow, caption_video (Add Captions), extend_video, remove_background, podcast_interview, quiz_video, reddit_story, scrolling_video. Dashboard-only formats: cinematic, article_to_video, pdf_to_video, pdf_to_brainrot, music_to_video, clone_video.
Available options:
all, ugc_video, ugc_ads, hook_demo, script_to_video, prompt_to_video, tiktok_slideshow, podcast_interview, scenes, cinematic, caption_video, remove_background, extend_video, scrolling_video, music_to_video, article_to_video, pdf_to_video, pdf_to_brainrot, reddit_story, quiz_video, clone_video Only videos in this state: STARTED (rendering), COMPLETED or FAILED. Case-insensitive; processing is read as STARTED. Any other value answers 400.
Available options:
STARTED, COMPLETED, FAILED Page size, 1 to 100. Larger values are capped at 100; missing or invalid values fall back to 50.
Required range:
1 <= x <= 100Videos to skip. Missing or invalid values fall back to 0. You are done when offset + limit >= total.
Required range:
x >= 0