Processing status
Follow a video from queued to ready by polling it, and handle failed processing.
After an upload or import, OctaVideo processes the video in the background; you follow it by reading the video until it is ready or failed.
Read the status
GET https://api.octavideo.tech/api/v1/videos/{videoId}
AccessKey: ovk_your_private_keyThree fields of the video tell you where processing is:
Prop
Type
{
"data": {
"id": "6f1c2b9e-4a7d-4f3e-9b8a-2d5c7e1f0a34",
"library_id": "0b8e5d3a-1c2f-4e6a-8b7d-9f0a1b2c3d4e",
"title": "Lesson 1: Introduction",
"description": "",
"encoding_status": "processing",
"progress": 42,
"stage": "transcode",
"duration_seconds": 754.2,
"size_bytes": 412337152,
"chapters": [],
"created_at": "2026-10-25T09:30:00Z"
}
}Status lifecycle
| Status | Meaning |
|---|---|
queued | The video is waiting for a processing slot. |
processing | OctaVideo is working on it; stage and progress show how far it is. |
ready | Processing finished. You can request a playback OTP. |
failed | Processing stopped; failure_reason says why. |
A video is encoded with the library's encoding settings as they were when it was queued. Changing the encoding settings later doesn't change videos already processed.
Processing stages
While processing, the video goes through these stages in order. Each one is a fixed share of progress:
| Stage | What happens | Share of progress |
|---|---|---|
fetch | OctaVideo reads the source file, or downloads it for an import. | 5% |
transcode | Each rendition is encoded, one per codec and resolution. | 55% |
thumbnails | The poster and thumbnails are captured. | 5% |
package | The renditions are packaged for HLS and DASH streaming. | 10% |
encrypt | The streams are encrypted with the video's own key. | 10% |
publish | The streams are published for delivery. | 8% |
meter | Encoding minutes and storage are recorded for billing. | 5% |
finalize | The video is marked ready. | 2% |
transcode takes most of the time, and it grows with the video's length and the number of renditions.
Poll until ready
To learn that a video is ready, use webhooks (recommended) or poll the video itself. This Node.js function waits for a video and backs off between checks:
const API = 'https://api.octavideo.tech/api/v1';
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
export async function waitUntilReady(videoId) {
let delay = 10_000; // start at 10 s
for (;;) {
const res = await fetch(`${API}/videos/${videoId}`, {
headers: { AccessKey: process.env.OCTAVIDEO_KEY },
});
if (!res.ok) throw new Error(`OctaVideo ${res.status}`);
const { data: video } = await res.json();
if (video.encoding_status === 'ready') return video;
if (video.encoding_status === 'failed') {
throw new Error(`Processing failed: ${video.failure_reason}`);
}
console.log(`${video.encoding_status} ${video.progress}% ${video.stage ?? ''}`);
await sleep(delay);
delay = Math.min(delay * 1.5, 30_000); // back off to 30 s
}
}- Poll every 10 to 30 seconds, and back off while the video is queued or transcoding.
- Stop as soon as the status is
readyorfailed. - To follow many videos, list them with List videos instead of reading each one. See Pagination and limits.
Prefer webhooks
With webhooks, OctaVideo calls your server with video.ready or video.failed the moment processing ends, so you don't poll at all.
When processing fails
OctaVideo retries a failing stage by itself, up to 5 times with a growing delay, before it marks the video failed. failure_reason then holds one of these codes:
failure_reason | Meaning | What to do |
|---|---|---|
invalid_media | The file isn't a video OctaVideo can read. | Check that the file plays on your computer, export it again, then upload the new file. |
max_attempts_exceeded | Processing failed 5 times in a row. | Select Retry encoding on the video in the console, or upload the file again. |
processing_error | An unexpected error stopped processing. | Retry once. If it fails again, write to support@octavideo.tech with the video ID. |
Treat any other value like processing_error.
What processing produces
A ready video has:
- An HLS and a DASH stream with every rendition, encrypted. The player picks the right one for each device.
- A poster image and a set of thumbnails. List video thumbnails returns their URLs once the thumbnails stage is done.
- Its
duration_seconds.