Common options
Options that work on every endpoint, for the viewport, waiting, blocking ads and cookie banners, injected CSS, locale, timeouts and caching.
These options work on /v1/screenshot, /v1/pdf and /v1/extract. With GET, pass them as query parameters. Arrays can be comma-separated, for example hide_selectors=.chat,.promo.
Page source#
| Parameter | Default | Description |
|---|---|---|
url |
Page to load. example.com becomes https://example.com. Private networks, localhost and non-HTTP schemes are refused. |
|
html |
Your own HTML, up to 5 MB. Send url or html, not both. |
Viewport and device#
| Parameter | Default | Description |
|---|---|---|
viewport |
1920×1080 |
{"width":1440,"height":900}, or viewport_width and viewport_height. 100–3840 px. |
device_scale_factor |
1 |
0.5–3 |
dark_mode |
false |
Sets prefers-color-scheme: dark |
user_agent |
Custom User-Agent string | |
locale |
en-US |
For example "tr-TR". Sets the browser language. |
timezone |
For example "Europe/Istanbul" |
Waiting#
| Parameter | Default | Description |
|---|---|---|
wait_until |
load |
load, domcontentloaded or networkidle. networkidle waits at most 5 seconds for the network to go quiet. |
wait_for_selector |
Wait until this element is visible. 422 SELECTOR_NOT_FOUND if it never appears. |
|
delay |
0 |
Extra wait in milliseconds after loading, up to 10,000 |
timeout |
20000 |
Total time for the render in milliseconds, 1,000–30,000 |
Cleaning up the page#
| Parameter | Default | Description |
|---|---|---|
block_ads |
false |
Block ad and tracker requests (EasyList, EasyPrivacy and uBlock filters) |
block_cookie_banners |
false |
Hide consent pop-ups from the common consent platforms and unlock scrolling |
hide_selectors |
Up to 50 CSS selectors to hide | |
css |
CSS injected before the capture, up to 50,000 characters |
Caching#
| Parameter | Default | Description |
|---|---|---|
cache |
false |
Return the stored result for identical requests |
cache_ttl |
3600 |
How long to keep it, in seconds, 60 to 604,800 (7 days) |
A cached response has X-Cache: HIT and counts as a render. See Caching, retries and performance.
Unknown and wrong options#
Unknown parameters are ignored. A known parameter with a wrong value returns 400 INVALID_PARAMETER, and the message names the parameter and the allowed values.
Stuck? Write to [email protected] with the request you sent and the error code you got back.