API reference

Capture (Screenshot)

Capture any webpage as PNG, JPEG, WebP or PDF — full page, element, or 18 real devices.

GEThttp://localhost:4000/v1/capture

Credit cost: 1 per successful request
Async: Supported (is_async)
404 billed: No
Plans: All plans

Authenticate with the x-api-key header. See authentication and credits & billing.

Parameters

Basics

Parameter	Description
`url` stringrequired	The URL of the webpage to capture. Example: `https://example.com`
`format` enum	Output format. Default: `png` Values:`pngjpegjpgwebppdf`
`image_quality` number	Quality 1-100 for jpeg/webp.
`selector` string	Capture a specific element instead of the viewport.

Viewport

Parameter	Description
`device` enum	Device to emulate (viewport, DPR, user agent, touch). Values:`iphone_14_pro_maxiphone_14_proiphone_13_pro_maxiphone_13_miniiphone_12iphone_xipadgalaxy_s23_ultragalaxy_s23galaxy_s8galaxy_fold4pixel_7_propixel_6apixel_5redmi_note_12_proredmi_note_11huawei_p60_prohuawei_mate_50_pro`
`full_page` boolean	Capture the entire page instead of just the viewport.
`full_page_scroll` boolean	Scroll the page to trigger lazy-loaded content before a full-page capture.
`full_page_scroll_duration` number	Time in milliseconds spent scrolling before the full-page capture.
`viewport_width` number	Viewport width in pixels. Default: `1920`
`viewport_height` number	Viewport height in pixels. Default: `1080`
`scale_factor` number	Device scale factor (1-3) for high-resolution screenshots. Default: `1`
`dark_mode` boolean	Emulate prefers-color-scheme: dark.

Cache

Parameter	Description
`cache` boolean	Cache the response at the edge.
`cache_ttl` number	Custom cache TTL in seconds (max 2,592,000 = 30 days, default 86,400).

Page

Parameter	Description
`remove_selectors` string	Comma-separated CSS selectors to hide before capturing (e.g. ads, popups).
`remove_cookie_banners` boolean	Automatically remove cookie banners before capturing.
`remove_ads` boolean	Automatically remove ads before capturing.
`block_resources` enum[]	Comma-separated list of resource types to block (e.g. image,stylesheet,font). Values (comma-separated):`documentstylesheetimagemediafontscripttexttrackxhrfetcheventsourcewebsocketmanifestother`
`block_urls` string	Comma-separated URL patterns to block (e.g. analytics,tracking,.example.com/).

Timing

Parameter Description

Parameter	Description
`delay` number	Delay in seconds before capturing (max 30).
`wait_until` enum[]	When to consider navigation finished. Default: `load` Values (comma-separated):`loaddomcontentloadednetworkidle0networkidle2`
`wait_for_selector` string	Wait for a specific element to appear before capturing.

delay

number

Delay in seconds before capturing (max 30).

wait_until

enum[]

When to consider navigation finished.

Default: load

Values (comma-separated):loaddomcontentloadednetworkidle0networkidle2

wait_for_selector

string

Wait for a specific element to appear before capturing.

Network

Parameter	Description
`proxy` string	Proxy to route the request through (http://user:pass@host:port, https:// or socks5://).
`stealth` boolean	Stealth mode: fingerprint hardening and user-agent rotation to reduce bot detection (paid plans).
`user_agent` string	Override the browser user agent.
`headers` json	Extra HTTP headers as a JSON object.
`cookies` json	Cookies to set, as a JSON array of {name,value,domain?,path?}.

Storage

Parameter	Description
`s3_access_key_id` string	S3 access key ID.
`s3_secret_key` string	S3 secret access key.
`s3_bucket` string	Bucket to upload the screenshot to.
`s3_object_key` string	Object key (auto-generated if empty).
`s3_region` string	S3 region.
`storage_endpoint` string	S3-compatible endpoint (e.g. https://<account>.r2.cloudflarestorage.com). Empty = AWS.
`s3_url` boolean	Upload and return JSON with the file URL instead of the binary image.

Global parameters

Accepted by every billable endpoint. Details in Global parameters.

Parameter	Description
`soft_fail` boolean	Return HTTP 200 even when an error occurs, with the message in `error`. Default: `false`
`is_async` boolean	Process asynchronously; returns a `job_id` to poll on /v1/jobs/{id}. Default: `false`
`fields` string	Comma-separated list of response fields to keep (dot notation for nested).
`webhook_url` string	With is_async=true, POST the finished job to this URL (signed, paid plans).

Code examples

curl -G "http://localhost:4000/v1/capture" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "format=png" \
  --data-urlencode "full_page=true" \
  -H "x-api-key: $SCREENSHOTDUDE_API_KEY" \
  -o screenshot.png

Responses

200 — binary file (default)

HTTP/1.1 200 OK
content-type: image/png        # image/jpeg, image/webp or application/pdf
x-cache: MISS
x-credits-charged: 1

<binary data>

200 — with s3_url=true

{
  "success": true,
  "data": {
    "url": "https://my-bucket.s3.eu-west-1.amazonaws.com/screens/acme-home.png",
    "key": "screens/acme-home.png",
    "bucket": "my-bucket"
  }
}

202 — with is_async=true

{
  "success": true,
  "job_id": "job_4f8k2m9q1x7c3v5b6n0z8l2p",
  "status": "Queued"
}

Response format

By default the response body is the file:

`format`	`Content-Type`
`png` (default)	`image/png`
`jpeg`, `jpg`	`image/jpeg`
`webp`	`image/webp`
`pdf`	`application/pdf`

Useful response headers: x-cache (HIT or MISS) and x-credits-charged.

With s3_url=true the file is uploaded to your bucket and the response is JSON { success, data: { url, key, bucket } } — see S3 / R2 upload. With is_async=true you get 202 and a job_id — see Async jobs.

Devices

device accepts one of 18 profiles: iphone_14_pro_max, iphone_14_pro, iphone_13_pro_max, iphone_13_mini, iphone_12, iphone_x, ipad, galaxy_s23_ultra, galaxy_s23, galaxy_s8, galaxy_fold4, pixel_7_pro, pixel_6a, pixel_5, redmi_note_12_pro, redmi_note_11, huawei_p60_pro, huawei_mate_50_pro. A device sets the viewport, device scale factor, user agent and touch support; it overrides viewport_width, viewport_height and scale_factor.

Waiting strategies

`wait_until`	Navigation is considered finished when…
`load` (default)	the `load` event fires
`domcontentloaded`	the HTML is parsed (fastest, images may be missing)
`networkidle0`	there are no network connections for 500 ms
`networkidle2`	there are at most 2 network connections for 500 ms

Combine with wait_for_selector (wait for an element) and delay (extra seconds, max 30).

Blocking

block_resources — comma-separated resource types: document, stylesheet, image, media, font, script, texttrack, xhr, fetch, eventsource, websocket, manifest, other.
block_urls — comma-separated substrings; any request URL containing one is aborted (for example analytics,tracking,doubleclick).
remove_selectors — elements hidden before capture.
remove_cookie_banners, remove_ads — automatic cleanup.

Headers and cookies

headers takes a JSON object and cookies a JSON array. URL-encode them:

curl -G "http://localhost:4000/v1/capture" \
  --data-urlencode "url=https://app.example/dashboard" \
  --data-urlencode 'headers={"Authorization":"Bearer abc123"}' \
  --data-urlencode 'cookies=[{"name":"session","value":"xyz","domain":"app.example"}]' \
  -H "x-api-key: $SNAPLENS_API_KEY" -o dashboard.png

Limits

Synchronous requests time out after 60 seconds (see Timeouts).
Private and internal network addresses are rejected with 400.
Extremely large outputs return 413 — capture a selector, lower scale_factor or use format=pdf.

Errors

Errors return JSON { "error": "…" }. Failed requests are never billed. Full list in Status codes.

Status	Meaning
400	Missing or invalid parameter (e.g. invalid URL, unsupported format, private network target)
401	Invalid, inactive or expired API key; plan rate limit (`Rate limit exceeded: …`) or key quota (`…: quota daily`)
403	`IP temporarily blocked` after repeated authentication failures; endpoint not included in your plan
402	`Payment required`, `You have open invoices: …` or `Insufficient credits: X required, Y available`
404	Target page not found — not billed
413	Result too large (e.g. extremely tall full-page capture)
500	Rendering failed or timed out (60 s) — not billed; retry or use `is_async=true`