--- title: "Get render job status" canonical_url: https://docs.zvid.io/docs/endpoints/get-render-job/ source: docs/endpoints/get-render-job.api.mdx content_revision: 6338386a1dd87e4a --- # 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](https://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 ```bash 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](#schema-render-job-timestamps) | 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** ```json { "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** ```json { "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** ```json { "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** ```json { "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** ```json { "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** ```json { "error": "server_error" } ``` ## Schema definitions The following definitions describe the fields referenced above. Expand a definition to inspect its complete contract. ### schema render job status **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](#schema-render-job-timestamps) | 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. ### schema render job timestamps **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. ### schema error **Error** Required properties: `error`. | Field | Type | Required | Description and constraints | | --- | --- | --- | --- | | `Error.error` | string | Yes | Error type | | `Error.message` | string | No | Human-readable error message | ### schema authentication error **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 | ## Related resources - [OpenAPI specification](https://docs.zvid.io/openapi.yaml) - [Project payload schema](https://docs.zvid.io/schemas/render-payload.schema.json) - [Quick Start](https://docs.zvid.io/docs/quick-start/) - [Authentication guide](https://docs.zvid.io/docs/authentication/)