Video Processing Status

When a video transformation is not cached yet, /t/ answers 202 and returns a statusUrl. Poll that URL until the status is completed, then request the /t/ URL again to get the bytes.

Include the transformation segment in the path. Jobs are keyed on the file path and the exact transformation parameters, and a bare file path parses as empty parameters, which never matches a queued job. Polling /video-status/clip.mp4 returns 404 even while that video is actively processing. Use the statusUrl from the 202 response verbatim.

Check status

GET /video-status/{transformations}/{path}

Auth: Public (rate limited)

Path parameters

string

required

The same transformation segment as the /t/ URL you are waiting on.w_640 · w_1280,h_720,c_fill

string

required

Storage path of the video file.videos/clip.mp4 · clip.mp4

Response

While a job exists. Note that completedAt and error are absent here rather than null:

{
  "status": "processing",
  "progress": 62,
  "startedAt": "2026-03-15T10:30:00.000Z"
}

string

One of pending · processing · completed · error · cancelled, or not_found on the 404 response.

number

Processing progress from 0 to 100. 0 when the job has not started.

string

ISO 8601 timestamp when processing started. The key is omitted while the job is still queued.

string

ISO 8601 timestamp when processing finished. The key is omitted until then.

string

Error message when status is error. The key is omitted otherwise.

Absent values are omitted from the JSON rather than sent as null. Test with "startedAt" in response, not response.startedAt !== null. This endpoint returns ISO 8601 strings; Queue Jobs serves raw database rows and returns the same instants as epoch milliseconds.

When the variant is already cached, the endpoint short-circuits and returns only the two fields it can prove:

{ "status": "completed", "progress": 100 }

When no job and no cached variant match:

{
  "status": "not_found",
  "message": "No processing job found for this video"
}

Status codes:

Code	Meaning
`200`	Job or cached variant found
`404`	No job and no cached variant for this exact URL

Example

curl http://localhost:3000/video-status/w_640/videos/clip.mp4

Get optimized video size

GET /video-status/{transformations}/{path}/size

Returns the byte size of the processed variant. Returns 404 if that variant is not ready yet. Auth: Public (rate limited)

Response

{
  "size": 2097152,
  "status": "ready"
}

number

Optimized video size in bytes.

string

Always "ready" when the endpoint returns 200.

Status codes: 200 ready · 404 not yet processed

Example

curl http://localhost:3000/video-status/w_640/videos/clip.mp4/size

Queue Events (SSE)

Real-time updates without polling.

Queue Jobs

Manage jobs by ID.

Transform Media

Apply transformations to videos.

Overview

Media

Files

Storage

Cache