POST /screenshot

Capture a Render of a public URL. Single endpoint: POST /screenshot.

Requires Authentication via Authorization: Bearer shot_….

Request body

Content-Type: application/json. Extra fields are rejected (400 invalid_input).

`url` (required)


Type	`string`
Example	`"https://example.com"`

Target URL. Must use http or https. Private, loopback, and link-local addresses are blocked (403 url_not_allowed).

`format`


Type	`"png"` \| `"jpeg"` \| `"webp"`
Default	`"png"`
Example	`"webp"`

Output image format.

`quality`


Type	`integer`
Default	`80`
Bounds	`1`–`100`
Example	`90`

JPEG/WebP compression quality. Ignored for PNG.

`viewport`


Type	`object`
Default	`{"width": 1280, "height": 720}`

Simulated browser window size before dpr scaling.

`viewport.width`


Type	`integer`
Default	`1280`
Bounds	`320`–`3840`

`viewport.height`


Type	`integer`
Default	`720`
Bounds	`240`–`2160`

`dpr`


Type	`integer`
Default	`1`
Allowed	`1`, `2`, `3`
Example	`2`

Device pixel ratio. Final image dimensions are viewport × dpr (unless full_page expands height).

`full_page`


Type	`boolean`
Default	`false`
Example	`true`

Capture the full scrollable page instead of the viewport. Maximum height is 32,768 px (422 page_too_tall if exceeded).

`block_ads`


Type	`boolean`
Default	`true`
Example	`false`

Block common ad and tracker domains via Playwright request interception.

`wait_until`


Type	`"load"` \| `"domcontentloaded"` \| `"networkidle"`
Default	`"load"`

Navigation lifecycle event before capture.

`wait_for`


Type	`string` \| `null`
Default	`null`
Example	`"#main-content"`

Optional CSS selector to wait for before screenshot. Must be syntactically valid and balanced. Returns 422 selector_not_found if the element never appears.

`delay`


Type	`integer` (milliseconds)
Default	`0`
Bounds	`0`–`10000`
Example	`500`

Extra wait after navigation and wait_for before capture.

`cache_ttl`


Type	`integer` (seconds)
Default	`300`
Bounds	`0`–`86400`
Example	`3600`

How long an identical request may be served from cache. 0 disables caching. See Caching & idempotency.

`response_type`


Type	`"image"` \| `"json"`
Default	`"image"`

"image" — raw bytes in the response body
"json" — JSON metadata with a hosted URL. See Storage.

Minimal request

{
  "url": "https://example.com"
}

Full request example

{
  "url": "https://example.com",
  "format": "webp",
  "quality": 85,
  "viewport": { "width": 1440, "height": 900 },
  "dpr": 2,
  "full_page": false,
  "block_ads": true,
  "wait_until": "networkidle",
  "wait_for": "#content",
  "delay": 250,
  "cache_ttl": 300,
  "response_type": "image"
}

Response: `response_type=image` (default)

HTTP/1.1 200 OK
Content-Type: image/png
X-Request-Id: req_01HW3QXP...
X-Render-Cached: false
X-Render-Billable: true
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 4
X-RateLimit-Reset: 1762624860
X-Quota-Limit: 100
X-Quota-Remaining: 99
X-Quota-Resets-At: 1764547200

<binary image bytes>

Content-Type reflects format (image/png, image/jpeg, or image/webp).

Curl: download PNG

curl -X POST http://localhost:8000/screenshot \
  -H 'Authorization: Bearer shot_yourkey_here' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com","format":"png"}' \
  -o screenshot.png

Response: `response_type=json`

{
  "url": "https://cdn.example.com/r/01HW3QXP9ZK4M2JQT6XBVCYNFD.webp",
  "format": "webp",
  "width": 2880,
  "height": 1800,
  "bytes": 142567,
  "cached": false,
  "billable": true,
  "render_duration_ms": 2341,
  "request_id": "req_01HW3QXP...",
  "expires_at": "2026-06-08T11:00:00Z"
}

Same rate-limit and quota headers as image mode apply on the HTTP response.

Curl: JSON with URL

curl -X POST http://localhost:8000/screenshot \
  -H 'Authorization: Bearer shot_yourkey_here' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com","response_type":"json","format":"webp","dpr":2}'

Optional headers

Header	Description
`Idempotency-Key`	Safe retry token. See Caching & idempotency.

Errors

See Errors for the complete code table. Validation failures return 400 invalid_input with field and issue.

Render wall time

Every Render is bounded by a 30-second wall-time budget. Exceeding it returns 503 render_timeout with timeout_ms: 30000.

POST /screenshot

On this page