Skip to the content
Docs Back to the site Dashboard

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
Authorizationrequired 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

urlrequiredstringThe public http or https page to capture.
full_pagebooleanCapture the whole scrollable page instead of the visible part.default false
selectorstringCapture only the first element matching this CSS selector. Up to 200 characters.
hide_selectorsarrayHide every element matching these CSS selectors. In a URL, separate them with commas. Up to 20.

How it looks

viewportstringScreen size as WIDTHxHEIGHT, for example 1440x900. Shortcut for viewport_width and viewport_height.
viewport_widthintegerWidth of the browser window, in pixels. 320 to 3,840.default 1440
viewport_heightintegerHeight of the browser window, in pixels. With full_page, the image is taller than this. 320 to 2,160.default 900
devicestringCapture 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.
orientationstringHold a phone or a tablet upright (portrait) or on its side (landscape). Needs a phone or tablet device. One of portrait, landscape.default portrait
device_scale_factornumberPixel density. 2 gives a sharper, larger image. 1 to 3.default 1
color_schemestringAsk the page for its light or dark theme. One of light, dark.
languagestringBrowser language, for example fr or fr-FR. Without it, a screenshot from a country uses the main language of that country.default en-US
timezonestringBrowser time zone, for example Europe/Paris. Without it, a screenshot from a country uses the main time zone of that country.
user_agentstringUser-Agent the page receives. A preset (googlebot, googlebot_mobile) or your own string. Useful to compare what a site shows to a crawler and to a visitor. A site that checks the crawler's IP address is not fooled. Up to 300 characters.
countrystringLoad 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.

Clean up

block_cookie_bannersbooleanRemoves most cookie banners. A banner the filters do not know stays in the picture.default false
block_adsbooleanBlock ads. Screenshots taken from a country block ads by default: set block_ads to false to see them. Without a country, ads stay unless you set it to true.
block_chat_widgetsbooleanHide chat bubbles.default false
close_popupsbooleanClose pop-ups and newsletter overlays.default false
hide_sticky_elementsbooleanHide headers, bars and buttons that stay fixed on screen.default false
disable_animationsbooleanFreeze animations and transitions.default false

When

wait_forstringWait until an element matching this CSS selector is visible. Up to 200 characters.
delay_msintegerExtra wait before the capture, in milliseconds. 0 to 5,000.default 0
click_selectorstringClick this one element before the screenshot, to open a menu, a tab or a dialog. A CSS selector matching exactly one element: use it when you know the code of the page. One click, no typing. Costs 1 more credit. Not with pdf, not with click_text. Up to 200 characters.
click_textstringSame click, pointed at by the text a visitor reads on the element, for example "Show all": use it when you do not know the code of the page. The whole text of exactly one visible button, tab or other clickable element, upper or lower case. Not a part of it, not a pattern. One click, no typing. Costs 1 more credit. Not with pdf, not with click_selector. Up to 80 characters.

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.

Click before the screenshot. One element is clicked once the page has loaded, then the picture is taken: an open menu, a tab, an accordion, a dialog. It is made for checking how your own pages look. Point at the element in one of two ways, never both. click_selector takes a CSS selector, when you know the code of the page. click_text takes the text a visitor reads on the element, for example Show all, when you do not: the whole text of one visible button, tab or other clickable element, in upper or lower case, never a part of it or a pattern. An icon without text is found by its accessible name. Either way the click must point to exactly one element that is visible and enabled, otherwise the request fails with click_target_invalid, and the error says whether none or several matched. Form fields, buttons that send a form, links to another page and downloads are refused with click_refused. If the click tries to send data, leave the page, open a window or download a file, it is stopped and the request fails with click_blocked. None of these failures is charged. One exception: a lot of sites report each click to an analytics tool. When what the page tries to send is such a report, to a known analytics endpoint, we hold it back (it is never sent) and still take the screenshot. The response then carries click.measurement_requests_held, the number of reports held. Read it for what it is: the page may have changed what it shows after the click, ordinary GET requests made by the click do go out, and a successful screenshot says neither that the click did something on the site nor that nothing was attempted. A screenshot with a click costs 1 credit more, is limited to 10 a minute and 100 a day. It does not work with format=pdf or in a batch. Click only on pages you are allowed to interact with: see the Acceptable use policy.

What comes back

formatstringFile 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
qualityintegerQuality for jpeg and webp. Ignored for png and pdf. 1 to 100.default 80
max_widthintegerScale the image down to this width. Useful to keep it small for a vision model. 320 to 3,840.
responsestringimage returns the picture itself. json returns its link, the page details and the attestation. One of image, json.default image
asyncbooleanReturn 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

Every code is on Errors.