Poll video status

Overview

After creating a video, use the returned uuid to poll for progress. The endpoint accepts the same X-API-Key you used to create the job.

GET {API_BASE}/v1/videos/{uuid}

Your API_BASE is shown in the Developer tab of your dashboard. The default production base is https://api.knowlify.com.

Authentication

Send your key in the X-API-Key header — the same key (personal or organization) that created the job.

X-API-Key: kn_<64 hex chars>

See Authentication for details on key issuance, rotation, and JWT alternatives.

Path parameters

string

required

The job ID returned in results[].uuid from POST /v1/videos.

Code examples

curl "https://api.knowlify.com/v1/videos/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: kn_YOUR_KEY_HERE"

const res = await fetch(`https://api.knowlify.com/v1/videos/${uuid}`, {
  headers: { "X-API-Key": "kn_YOUR_KEY_HERE" },
});
const status = await res.json();
if (status.is_complete) {
  console.log("Video ready");
}

import requests

resp = requests.get(
    f"https://api.knowlify.com/v1/videos/{uuid}",
    headers={"X-API-Key": "kn_YOUR_KEY_HERE"},
    timeout=15,
)
resp.raise_for_status()
status = resp.json()
if status["is_complete"]:
    print("Video ready")

Response

string

The job ID (echoes the path parameter).

string

Current pipeline stage. One of: pending, queued, voiceover, highlevel, lowlevel, scan_assets, generating_frames, complete, failed.

boolean

true once rendering finished successfully.

boolean

true if the job stopped due to an unrecoverable error. Inspect error_message.

object

Show progress fields

string

Same as top-level status.

integer

Coarse 0–100 progress estimate. Stage-driven, with a finer-grained band during generating_frames based on current_scene / total_scenes.

integer

Scenes rendered so far (only meaningful during generating_frames).

integer

Total scenes for this video.

string

Human-readable failure reason. null on healthy jobs.

string

The original task prompt for this job (echoed for convenience).

string

ISO-8601 timestamp when the job was first queued.

string

ISO-8601 timestamp of the last status change. Use this to detect stalled jobs.

Example response (mid-render)

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "generating_frames",
  "is_complete": false,
  "is_failed": false,
  "progress": {
    "stage": "generating_frames",
    "percent": 88,
    "current_scene": 4,
    "total_scenes": 5
  },
  "error_message": null,
  "task": "Explain how HTTPS works in 30 seconds",
  "created_at": "2026-04-25T12:34:56.789012+00:00",
  "updated_at": "2026-04-25T12:36:18.123456+00:00"
}

Example response (complete)

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "complete",
  "is_complete": true,
  "is_failed": false,
  "progress": { "stage": "complete", "percent": 100, "current_scene": 5, "total_scenes": 5 },
  "error_message": null,
  "task": "Explain how HTTPS works in 30 seconds",
  "created_at": "2026-04-25T12:34:56.789012+00:00",
  "updated_at": "2026-04-25T12:39:42.500000+00:00"
}

Poll at most once every 5 seconds — status changes are stage-level, not per-frame. Production integrations should subscribe to Supabase realtime updates on the corporate_engine_v2 table. Reach out for a Supabase anon key scoped to your account.

Limits & errors

The same 30 requests / 60 seconds rate limit applies to polling. See Rate Limits.
Full status code reference: Errors.

Overview

Guides

Endpoints

Poll video status

Overview

Authentication

Path parameters

Code examples

Response

Example response (mid-render)

Example response (complete)

Limits & errors

​Overview

​Authentication

​Path parameters

​Code examples

​Response

​Example response (mid-render)

​Example response (complete)

​Limits & errors

Overview

Authentication

Path parameters

Code examples

Response

Example response (mid-render)

Example response (complete)

Limits & errors