Retrieve a job
GET
upscalr.app/api/v1/jobs/{id}Fetches the current state of a job. Poll it every second or two until the status settles, or skip polling entirely with a webhook.
Request
| Parameter | Type | Description |
|---|---|---|
| id | path, required | The job id returned when it was created. |
curl https://upscalr.app/api/v1/jobs/cmrw0iqm8000bdcs3um6ii7fa \
-H "Authorization: Bearer $UPSCALR_API_KEY"Requires the jobs:read scope.
Job lifecycle
| Parameter | Type | Description |
|---|---|---|
| pending | status | Accepted, waiting to enter the queue. |
| queued | status | In the queue, not yet picked up by the engine. |
| processing | status | The engine is working on it. |
| succeeded | status | Finished. The result is ready to download. |
| failed | status | The engine gave up; credits were refunded. error explains why. |
| cancelled | status | Cancelled before finishing; credits were refunded. |
Response
Response · 200 OK
{
"id": "cmrw0iqm8000bdcs3um6ii7fa",
"object": "job",
"status": "succeeded",
"target": "4k",
"filename": "photo.png",
"credits": 3,
"error": null,
"source": {
"bytes": 2148393,
"content_type": "image/png"
},
"result": {
"bytes": 8412930,
"content_type": "image/png",
"url": "/api/v1/jobs/cmrw0iqm8000bdcs3um6ii7fa/result"
},
"created_at": "2026-07-25T09:30:00Z",
"finished_at": "2026-07-25T09:30:04Z",
"duration_ms": 4210
}| Status | Meaning |
|---|---|
| 200 | The job. |
| 404 | No job with that id. |
The job object
| Parameter | Type | Description |
|---|---|---|
| id | string | Unique job id. |
| object | string | Always "job". |
| status | string | One of the lifecycle states above. |
| target | string | The output size actually used (the engine may fall back; see Introduction). |
| filename | string | null | Original filename, when known. |
| credits | integer | Credits reserved or charged for this job. |
| error | object | null | Set when status is failed: { code, message }. |
| source | object | null | Size and content type of the input. |
| result | object | null | Size, content type and download path of the output. Present once succeeded. |
| created_at | timestamp | When the job was created (ISO 8601, UTC). |
| finished_at | timestamp | null | When it reached a final state. |
| duration_ms | integer | null | Wall-clock processing time. |
Need the full history instead of one job? See List jobs.