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.

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

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

Auth: Public (rate limited)

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

Param	In	Type	Notes
`transformations`	path	string	Required. The same transformation segment as the `/t/` URL you are waiting on, such as `w_640`
`path`	path	string	Required. Storage path of the video file, such as `videos/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"
}

Field	Type	Notes
`status`	string	`pending` `processing` `completed` `error` `cancelled`, or `not_found` on the `404` response
`progress`	number	Processing progress from 0 to 100. `0` when the job has not started
`startedAt`	string	ISO 8601 timestamp when processing started. Omitted while the job is still queued
`completedAt`	string	ISO 8601 timestamp when processing finished. Omitted until then
`error`	string	Error message when `status` is `error`. 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"
}

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

Get optimized video size

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

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

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

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

Field	Type	Notes
`size`	number	Optimized video size in bytes
`status`	string	Always `"ready"` when the endpoint returns 200

Status codes: 200 ready · 404 not yet processed

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