> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openinary.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Video Processing Status

> Poll the processing status of a queued video transformation

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.

```bash theme={null}
curl https://cdn.openinary.dev/video-status/w_640/videos/clip.mp4 \
  -H "Authorization: Bearer <api_key>"
```

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

**Auth:** API key on Cloud, public and rate limited self-hosted. Drop the header when you call your own instance.

> [!WARNING]
>
> 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`:

```json theme={null}
{
  "status": "processing",
  "progress": 62,
  "startedAt": "2026-03-15T10:30:00.000Z",
  "phase": "processing",
  "estimatedSeconds": 8,
  "estimatedRange": [8, 10],
  "retryAfter": 8
}
```

| 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, measured from the encoder. `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 |
| `phase` | string | `waking`, `queued` or `processing`, while the job is `pending` or `processing`. Omitted otherwise |
| `estimatedSeconds` | number | Typical seconds left, while the job is `pending` or `processing` |
| `estimatedRange` | `[number, number]` | Typical and pessimistic seconds left |
| `retryAfter` | number | When polling again is worth it, in seconds |

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](https://docs.openinary.dev/api-reference/queue/jobs.md) 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:

```json theme={null}
{ "status": "completed", "progress": 100 }
```

When no job and no cached variant match:

```json theme={null}
{
  "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:** API key on Cloud, public and rate limited self-hosted.

```bash theme={null}
curl https://cdn.openinary.dev/video-status/w_640/videos/clip.mp4/size \
  -H "Authorization: Bearer <api_key>"
```

```json theme={null}
{
  "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

## Related

> [card] [Queue Events (SSE)](https://docs.openinary.dev/api-reference/queue/events.md)
>
> Real-time updates without polling.

> [card] [Queue Jobs](https://docs.openinary.dev/api-reference/queue/jobs.md)
>
> Manage jobs by ID.

> [card] [Transform Media](https://docs.openinary.dev/api-reference/media/transform.md)
>
> Apply transformations to videos.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.