Screenshot (image / PDF)

POST /v1/screenshot — synchronous render, returns a URL to the file.

curl https://websitescreenshotapi.net/api/v1/screenshot \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://news.ycombinator.com",
    "format": "png",
    "full_page": true,
    "block_ads": true,
    "viewport_width": 1920
  }'

Required

Field	Type	Description
`url`	string	Target URL. Must start with `http://` or `https://`

Optional

Output

Field	Type	Default	Notes
`format`	string	`png`	`png`, `jpg`, `jpeg`, `webp`, `pdf`
`quality`	int 20-100	80	JPEG / WebP quality
`full_page`	bool	false	Capture the entire scrollable page
`selector`	string	—	CSS selector to clip to (e.g. `#hero`)
`clip`	object	—	`{x, y, width, height}` for a custom clip region
`omit_background`	bool	false	Transparent background (PNG only)
`pdf_paper`	string	`A4`	`A4`, `Letter`, `Legal`, `Tabloid`

Viewport

Field	Type	Default	Notes
`viewport_width`	int 320-3840	1920
`viewport_height`	int 240-2400	1080
`device_scale_factor`	float 1.0-3.0	1	Retina = 2
`device`	string	—	Preset: `iphone_15_pro`, `pixel_7`, `ipad_pro_11`, `galaxy_s9`, `macbook_pro_16`, `desktop_1440x900`, `desktop_1366x768`
`dark_mode`	bool	false	`prefers-color-scheme: dark`
`reduced_motion`	bool	false	`prefers-reduced-motion: reduce`

Loading & timing

Field	Type	Default	Notes
`wait_until`	string	`load`	`load`, `domcontentloaded`, `networkidle`, `commit`
`wait_for_selector`	string	—	Wait for element to appear before capture
`delay`	int 0-10000 ms	0	Extra wait after load

Blocking

Field	Type	Default	Notes
`block_ads`	bool	false	Blocks Google Ads, DoubleClick, Adsense, Criteo, Taboola, etc.
`block_cookie_banners`	bool	false	OneTrust, Cookiebot, Didomi, Quantcast, Usercentrics, TrustArc
`block_chat_widgets`	bool	false	Hides Intercom, Crisp, Drift, Tawk.to via CSS

Auth & headers

Field	Type	Notes
`basic_auth`	string	`user:pass` for HTTP Basic Auth
`cookies`	array	Playwright cookie objects: `[{name, value, domain, path}]`
`headers`	object	Extra HTTP headers: `{"X-Custom": "..."}`
`user_agent`	string	Override UA
`locale`	string	e.g. `en-US`, `fr-FR`

Response

{
  "url":              "https://websitescreenshotapi.net/files/123/job_abc-def.png",
  "expires_at":       "2026-05-07T14:23:00+00:00",
  "retention_hours":  24,
  "format":           "png",
  "size_bytes":       234567,
  "width":            1920,
  "height":           1080,
  "duration_ms":      512,
  "credits_charged":   2,
  "credits_remaining": 1898,
  "plan_code":        "basic",
  "job_id":           "job_abc",
  "cache_hit":        false
}

The endpoint is synchronous — it waits for the render to finish (up to 30s) before responding.

If render takes > 30s, response is 202 processing with db_id to poll via GET /v1/screenshot/{db_id}.

For high-throughput use cases, prefer POST /v1/screenshot-async (see Async + bulk + webhooks).

Cost

What	Units
Image (PNG/JPG/WebP)	1
PDF	2
`+ full_page`	+1
`+ stealth`	+3
`+ premium_proxy`	+5