Screenshots

Take a screenshot

GETPOST/v1/screenshot

Takes a screenshot of a public web page and waits for it. By default the answer is the image. With GET, options go in the address. With POST, they go in a JSON body.

Headers

Header	Description
`Authorization`required	`Bearer` followed by your API key. The key is never accepted in the address. See Your API key.
`Idempotency-Key`	Makes a retry safe: the same key returns the same screenshot and is charged once. 8 to 128 letters, digits, dashes, dots, colons or underscores. See Retries and Idempotency-Key.

What to capture

`url`requiredstring	The public http or https page to capture.
`full_page`boolean	Capture the whole scrollable page instead of the visible part.default `false`
`selector`string	Capture only the first element matching this CSS selector. Up to 200 characters.
`hide_selectors`array	Hide every element matching these CSS selectors. In a URL, separate them with commas. Up to 20.

How it looks

`viewport`string	Screen size as WIDTHxHEIGHT, for example 1440x900. Shortcut for viewport_width and viewport_height.
`viewport_width`integer	Width of the browser window, in pixels. 320 to 3,840.default `1440`
`viewport_height`integer	Height of the browser window, in pixels. With full_page, the image is taller than this. 320 to 2,160.default `900`
`device`string	Capture as this device (screen size, pixel density, mobile browser). One of `desktop`, `desktop_hd`, `laptop`, `ipad`, `ipad_pro`, `ipad_mini`, `iphone_15`, `iphone_15_pro_max`, `iphone_se`, `pixel_8`, `galaxy_s24`.
`device_scale_factor`number	Pixel density. 2 gives a sharper, larger image. 1 to 3.default `1`
`color_scheme`string	Ask the page for its light or dark theme. One of `light`, `dark`.
`language`string	Browser language, for example fr or fr-FR.default `en-US`
`timezone`string	Browser time zone, for example Europe/Paris.
`country`string	Load the page from this country (ISO 3166-1 alpha-2 code, see /v1/countries). The response reports the country actually observed. If it cannot be obtained, the request fails and is not charged. Costs 2 credits instead of 1.

Not open to every account yet. Screenshots from a chosen country are being opened account by account. Until yours is, a request with country is refused with option_unavailable before anything is captured.

Clean up

`block_cookie_banners`boolean	Removes most cookie banners. A banner the filters do not know stays in the picture.default `false`
`block_ads`boolean	Block ads.default `false`
`block_chat_widgets`boolean	Hide chat bubbles.default `false`
`close_popups`boolean	Close pop-ups and newsletter overlays.default `false`
`hide_sticky_elements`boolean	Hide headers, bars and buttons that stay fixed on screen.default `false`
`disable_animations`boolean	Freeze animations and transitions.default `false`

When

`wait_for`string	Wait until an element matching this CSS selector is visible. Up to 200 characters.
`delay_ms`integer	Extra wait before the capture, in milliseconds. 0 to 5,000.default `0`

We wait for the page to load and for its network to calm down before the picture. Use wait_for when the part you want appears late, and delay_ms for an animation that needs a moment.

What comes back

`format`string	File format. pdf saves the whole page as a document; it cannot be combined with selector or max_width. One of `png`, `jpeg`, `webp`, `pdf`.default `png`
`quality`integer	Quality for jpeg and webp. Ignored for png and pdf. 1 to 100.default `80`
`max_width`integer	Scale the image down to this width. Useful to keep it small for a vision model. 320 to 3,840.
`response`string	image returns the picture itself. json returns its link, the page details and the attestation. One of `image`, `json`.default `image`
`async`boolean	Return an id right away instead of waiting. Read the result at /v1/screenshots/{id}.default `false`

An option we do not know is refused with invalid_request, never ignored. selector and full_page cannot be used together. A pdf is always the whole page: it cannot be combined with selector or max_width.

Response

The image, with these headers. With response=json, a JSON document instead. If the screenshot is still running when the wait ends (after 50 seconds), or with async=true, you get 202 and a Location header to read it later: see Run in the background.

Header	Description
`X-Screenshot-Id`	The id of the screenshot.
`X-Credits-Charged`	Credits this screenshot used.
`X-Credits-Remaining`	Credits you have left.
`X-Page-Status`	What the page answered, for example 200 or 404. A page that answers 404 or 451 is still captured and charged.
`X-Country-Observed`	Only with `country`: the country the page was really loaded from.

A pdf is sent as a file to download, not shown in the browser.

Limits of one screenshot

Only public http and https pages. A private or local address is refused with url_not_allowed.
A page has 35 seconds to load. After that the screenshot fails with timeout.
A page heavier than 10 MB to download fails with page_too_heavy. Video and audio are not loaded.
When a site shows a bot check instead of its page, the screenshot fails with challenge_page. We do not solve CAPTCHAs.

Every code is on Errors.

NextRead a screenshot