---
title: "Get the state of a background job"
method: GET
path: "/api/v1/jobs/{id}"
tags: ["Jobs"]
---

# Get the state of a background job

`GET /api/v1/jobs/{id}`

## Request

- Base URL: `https://curlshot.com`
- URL: `https://curlshot.com/api/v1/jobs/{id}`
- Auth: one of:
  - API key in query parameter `access_key`
  - API key in header `X-Access-Key`
  - HTTP bearer

## Path parameters

- `id` string, required

## Response `200`

The job.

- Job
  - `job_id` string, required
  - `batch_id` string, nullable
  - `status` 'queued' | 'processing' | 'done' | 'failed', required
  - `job_url` string, uri, required
  - `screenshot` ScreenshotFile
    - `id` string, required: Reference id of the render.
    - `url` string, uri, nullable, required: Link to the stored file. It carries its own expiring token and needs no access key.
    - `format` 'png' | 'jpeg' | 'webp' | 'pdf' | 'mp4' | 'webm' | 'gif', required
    - `bytes` integer, required
    - `width` integer, nullable
    - `height` integer, nullable
    - `render_ms` integer, nullable
    - `cached` boolean: True when a stored copy was served.
    - `expires_at` string, date-time, nullable: When the stored file is removed and its link stops working.
  - `error_code` 'invalid_url' | 'host_not_allowed' | 'navigation_failed' | 'timeout' | 'selector_not_found' | 'page_blocked' | 'concurrency_limit' | 'content_too_large' | 'internal_error' | 'renderer_busy' | 'renderer_unavailable' | 'invalid_options' | 'access_key_required' | 'access_key_invalid' | 'signature_required' | 'signature_invalid' | 'quota_exceeded' | 'rate_limited' | 'job_not_found' | 'service_unavailable' | 'invalid_request' | 'email_not_verified' | 'feature_not_available' | 'request_expired' | 'not_found' | 'file_not_found' | 'method_not_allowed' | 'queue_limit' | 'failure_limit' | 'null', nullable
  - `error_message` string, nullable
  - `created_at` string, date-time
  - `finished_at` string, date-time, nullable

## Other responses

- `401`: `access_key_required`: An access key is required. Pass `access_key` or the `X-Access-Key` header. `access_key_invalid`: The access key is not valid or has been revoked.
- `403`: `signature_required`: This access key only accepts signed requests. Add a `signature` parameter. `signature_invalid`: The request signature does not match. `request_expired`: This request has expired: its `expires` time is in the past. Create a new link with a later `expires`.
- `404`: `job_not_found`: No job with this id exists for your account.
- `429`: `rate_limited`: Too many requests. Slow down and retry after the indicated delay.
- `503`: `service_unavailable`: The service is temporarily unavailable. Retry in a moment.

---

[API](https://skmtc.dev/curlshot/apis/curlshot-api.md) · [All operations](https://skmtc.dev/curlshot/apis/curlshot-api/llms.txt) · [OpenAPI document](https://skmtc.dev/curlshot/apis/curlshot-api/revisions/2022db7875af?raw)