Skip to main content

​
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

​
uuid
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"

​
Response

​
uuid
string
The job ID (echoes the path parameter).
​
status
string
Current pipeline stage. One of: pending, queued, voiceover, highlevel, lowlevel, scan_assets, generating_frames, complete, failed.
​
is_complete
boolean
true once rendering finished successfully.
​
is_failed
boolean
true if the job stopped due to an unrecoverable error. Inspect error_message.
​
progress
object
​
error_message
string
Human-readable failure reason. null on healthy jobs.
​
task
string
The original task prompt for this job (echoed for convenience).
​
created_at
string
ISO-8601 timestamp when the job was first queued.
​
updated_at
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.