Poll video status

These pages describe the Training API on dev, where authenticated creation, editing, downloads, revert, and website brand lookup have been tested live. Production availability is not confirmed. Your API service and worker must both run the updated code. See Testing and availability.

GET {API_BASE}/v1/videos/{uuid} Use a key whose workspace can access the target video. See Authentication.

curl --fail-with-body "$API_BASE/v1/videos/$VIDEO_UUID" \
  -H "X-API-Key: $KNOWLIFY_API_KEY"

Response

Field	Meaning
`uuid`	Video identifier
`status`	Pipeline stage; treat stage names as extensible
`render_status`	Underlying render state, such as `COMPLETED`; may be null
`video_url`	Available combined video URL, or null
`is_complete`	True when rendering is `COMPLETED` and the stage is `complete` or `conversation_complete`
`is_failed`	True on a detected pipeline or render failure; check this before handling completion
`progress`	Coarse `stage` and `percent`, with scene counts when available
`required_action`	A creation question or failed-scene retry action; otherwise null
`error_message`	Failure reason, or null
`task`	Original instruction
`created_at`, `updated_at`	Creation and latest update timestamps

Planning can finish before rendering. Do not treat status: "complete" alone as success. Unfinished, healthy jobs remain below 100 percent. If required_action.kind is clarification, read its question IDs, options, and round. Answer or skip the question to resume. If the kind is scene_retry, retry failed scenes. A paused video does not use an active API generation slot.

// Run on your server, with VIDEO_UUID from the creation response.
const response = await fetch(
  `${process.env.API_BASE}/v1/videos/${process.env.VIDEO_UUID}`,
  { headers: { "X-API-Key": process.env.KNOWLIFY_API_KEY } },
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const video = await response.json();
if (video.is_failed) throw new Error(video.error_message || "Rendering failed");
if (video.is_complete) {
  console.log(video.video_url || "Complete; no combined file is available");
}

Poll about every five seconds and back off on errors. Stop on success, failure, or an application-defined timeout. A combined file can arrive later; long videos may remain a playlist, so a completed job does not guarantee a non-null video_url. This endpoint does not expose the full planner, timestamps, or a playlist manifest.

Downloading the video

For media in Knowlify’s configured S3 bucket, video_url is a signed URL valid for one hour. Download it directly without adding your Knowlify API key. Poll this endpoint again to obtain a fresh URL after expiration. Other media URLs keep their provider’s access rules.

Overview

Guides

Endpoints

Poll video status

Response

Downloading the video

​Response

​Downloading the video

Response

Downloading the video