Get render job status
GET /api/jobs/{id}
Retrieve the status, progress, and result of a render job by ID.
Authentication
- Option 1:
x-api-key: YOUR_API_KEY(header). API key for authentication. Create one in your dashboard. - Option 2:
Authorization: Bearer YOUR_ACCESS_TOKEN. Dashboard JWT in Authorization: Bearer <token>, only on operations that explicitly list this scheme. Prefer x-api-key for REST integrations. OAuth for hosted MCP is a separate connection at https://mcp.zvid.io/mcp.
Create API keys at app.zvid.io/api-keys. Keep credentials on your server.
Parameters
| Parameter | Location | Type | Required | Description and constraints |
|---|---|---|---|---|
id | path | string | Yes | Render job ID |
Request
The shell examples read credentials from ZVID_API_KEY (or ZVID_ACCESS_TOKEN for Bearer authentication). Set that variable in your environment. Replace sample project, template, job, and asset identifiers with values from your own account.
This operation does not take a request body.
Request example
curl --request GET 'https://api.zvid.io/api/jobs/550e8400-e29b-41d4-a716-446655440000' \
--header "x-api-key: $ZVID_API_KEY"
Responses
HTTP 200
Render job found
Content type: application/json.
Unknown properties are rejected. Required properties: id, state, progress, ts.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
response.id | string | Yes | Job identifier |
response.state | string / null | Yes | Queue states include waiting, prioritized, active, delayed, completed and failed. Treat completed/failed as terminal; keep polling other states with bounded backoff. |
response.progress | number OR object | Yes | A percentage or phase object. The structured progress field is percentage, not percent. Exactly one of the listed alternatives must match. |
response.result | string OR object OR null | No | Usually an object with url while queue data is available. Persisted history can return the output URL string. Handle both shapes. Exactly one of the listed alternatives must match. |
response.failedReason | string / null | No | Failure reason if the job failed |
response.ts | RenderJobTimestamps | Yes |
Nested field: response.progress
A percentage or phase object. The structured progress field is percentage, not percent.
Exactly one of the listed alternatives must match.
oneOf alternative 1
Minimum: 0. Maximum: 100.
Type: number.
oneOf alternative 2
| Field | Type | Required | Description and constraints |
|---|---|---|---|
response.progress.phase | string | No | |
response.progress.percentage | number | No | |
response.progress.message | string | No |
Nested field: response.result
Usually an object with url while queue data is available. Persisted history can return the output URL string. Handle both shapes.
Exactly one of the listed alternatives must match.
oneOf alternative 1
Type: string.
oneOf alternative 2
| Field | Type | Required | Description and constraints |
|---|---|---|---|
response.result.url | string | No | |
response.result.thumbnailUrl | string OR null | No | At least one listed alternative must match. |
response.result.type | "video" / "image" | No | |
response.result.duration | number OR null | No | At least one listed alternative must match. |
response.result.size | number OR null | No | At least one listed alternative must match. |
Nested field: response.result.thumbnailUrl
At least one listed alternative must match.
anyOf alternative 1
Type: string.
anyOf alternative 2
Type: null.
Nested field: response.result.duration
At least one listed alternative must match.
anyOf alternative 1
Type: number.
anyOf alternative 2
Type: null.
Nested field: response.result.size
At least one listed alternative must match.
anyOf alternative 1
Type: number.
anyOf alternative 2
Type: null.
oneOf alternative 3
Type: null.
Example response
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"state": "completed",
"progress": 100,
"result": "https://cdn.zvid.io/videos/123/video.mp4",
"failedReason": null,
"ts": {
"created": "2025-01-20T12:00:00.000Z",
"updated": "2025-01-20T12:05:00.000Z",
"finished": "2025-01-20T12:05:00.000Z"
}
}
HTTP 400
Invalid job ID
Content type: application/json.
Required properties: error.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
response.error | string | Yes | Error type |
response.message | string | No | Human-readable error message |
Example response
{
"error": "Invalid job ID",
"message": "Job ID must be a valid UUID"
}
HTTP 401
Authentication required
Content type: application/json.
Unknown properties are rejected. Required properties: error.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
response.error | string | Yes | Error type |
response.message | string | No | Human-readable error message |
Example response
{
"error": "Authentication required",
"message": "Please provide an API key in the X-API-Key header or Authorization header"
}
HTTP 403
Access denied – job does not belong to the authenticated user
Content type: application/json.
Required properties: error.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
response.error | string | Yes | Error type |
response.message | string | No | Human-readable error message |
Example response
{
"error": "Access denied",
"message": "Access denied"
}
HTTP 404
Job not found
Content type: application/json.
Required properties: error.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
response.error | string | Yes | Error type |
response.message | string | No | Human-readable error message |
Example response
{
"error": "Job not found"
}
HTTP 500
Internal server error
Content type: application/json.
Required properties: error.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
response.error | string | Yes | Error type |
response.message | string | No | Human-readable error message |
Example response
{
"error": "server_error"
}
Schema definitions
The following definitions describe the fields referenced above. Expand a definition to inspect its complete contract.
RenderJobStatus
Unknown properties are rejected. Required properties: id, state, progress, ts.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
RenderJobStatus.id | string | Yes | Job identifier |
RenderJobStatus.state | string / null | Yes | Queue states include waiting, prioritized, active, delayed, completed and failed. Treat completed/failed as terminal; keep polling other states with bounded backoff. |
RenderJobStatus.progress | number OR object | Yes | A percentage or phase object. The structured progress field is percentage, not percent. Exactly one of the listed alternatives must match. |
RenderJobStatus.result | string OR object OR null | No | Usually an object with url while queue data is available. Persisted history can return the output URL string. Handle both shapes. Exactly one of the listed alternatives must match. |
RenderJobStatus.failedReason | string / null | No | Failure reason if the job failed |
RenderJobStatus.ts | RenderJobTimestamps | Yes |
Nested field: RenderJobStatus.progress
A percentage or phase object. The structured progress field is percentage, not percent.
Exactly one of the listed alternatives must match.
oneOf alternative 1
Minimum: 0. Maximum: 100.
Type: number.
oneOf alternative 2
| Field | Type | Required | Description and constraints |
|---|---|---|---|
RenderJobStatus.progress.phase | string | No | |
RenderJobStatus.progress.percentage | number | No | |
RenderJobStatus.progress.message | string | No |
Nested field: RenderJobStatus.result
Usually an object with url while queue data is available. Persisted history can return the output URL string. Handle both shapes.
Exactly one of the listed alternatives must match.
oneOf alternative 1
Type: string.
oneOf alternative 2
| Field | Type | Required | Description and constraints |
|---|---|---|---|
RenderJobStatus.result.url | string | No | |
RenderJobStatus.result.thumbnailUrl | string OR null | No | At least one listed alternative must match. |
RenderJobStatus.result.type | "video" / "image" | No | |
RenderJobStatus.result.duration | number OR null | No | At least one listed alternative must match. |
RenderJobStatus.result.size | number OR null | No | At least one listed alternative must match. |
Nested field: RenderJobStatus.result.thumbnailUrl
At least one listed alternative must match.
anyOf alternative 1
Type: string.
anyOf alternative 2
Type: null.
Nested field: RenderJobStatus.result.duration
At least one listed alternative must match.
anyOf alternative 1
Type: number.
anyOf alternative 2
Type: null.
Nested field: RenderJobStatus.result.size
At least one listed alternative must match.
anyOf alternative 1
Type: number.
anyOf alternative 2
Type: null.
oneOf alternative 3
Type: null.
RenderJobTimestamps
Unknown properties are rejected. Required properties: created, updated, finished.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
RenderJobTimestamps.created | integer OR string OR null | Yes | Exactly one of the listed alternatives must match. |
RenderJobTimestamps.updated | integer OR string OR null | Yes | Exactly one of the listed alternatives must match. |
RenderJobTimestamps.finished | integer OR string OR null | Yes | Exactly one of the listed alternatives must match. |
Nested field: RenderJobTimestamps.created
Exactly one of the listed alternatives must match.
oneOf alternative 1
Unix milliseconds while job data is in the queue.
Type: integer.
oneOf alternative 2
ISO date-time when served from persisted job history.
Format: date-time.
Type: string.
oneOf alternative 3
Type: null.
Nested field: RenderJobTimestamps.updated
Exactly one of the listed alternatives must match.
oneOf alternative 1
Unix milliseconds while job data is in the queue.
Type: integer.
oneOf alternative 2
ISO date-time when served from persisted job history.
Format: date-time.
Type: string.
oneOf alternative 3
Type: null.
Nested field: RenderJobTimestamps.finished
Exactly one of the listed alternatives must match.
oneOf alternative 1
Unix milliseconds while job data is in the queue.
Type: integer.
oneOf alternative 2
ISO date-time when served from persisted job history.
Format: date-time.
Type: string.
oneOf alternative 3
Type: null.
Error
Required properties: error.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
Error.error | string | Yes | Error type |
Error.message | string | No | Human-readable error message |
AuthenticationError
Unknown properties are rejected. Required properties: error.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
AuthenticationError.error | string | Yes | Error type |
AuthenticationError.message | string | No | Human-readable error message |