Screenshots
Take a screenshot
/v1/screenshotTakes 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
urlrequiredstring | The public http or https page to capture. |
full_pageboolean | Capture the whole scrollable page instead of the visible part.default false |
selectorstring | Capture only the first element matching this CSS selector. Up to 200 characters. |
hide_selectorsarray | Hide every element matching these CSS selectors. In a URL, separate them with commas. Up to 20. |
How it looks
viewportstring | Screen size as WIDTHxHEIGHT, for example 1440x900. Shortcut for viewport_width and viewport_height. |
viewport_widthinteger | Width of the browser window, in pixels. 320 to 3,840.default 1440 |
viewport_heightinteger | Height of the browser window, in pixels. With full_page, the image is taller than this. 320 to 2,160.default 900 |
devicestring | 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. |
orientationstring | Hold 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_factornumber | Pixel density. 2 gives a sharper, larger image. 1 to 3.default 1 |
color_schemestring | Ask the page for its light or dark theme. One of light, dark. |
languagestring | Browser language, for example fr or fr-FR. Without it, a screenshot from a country uses the main language of that country.default en-US |
timezonestring | Browser time zone, for example Europe/Paris. Without it, a screenshot from a country uses the main time zone of that country. |
user_agentstring | User-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. |
countrystring | 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. |
Clean up
block_cookie_bannersboolean | Removes most cookie banners. A banner the filters do not know stays in the picture.default false |
block_adsboolean | Block 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_widgetsboolean | Hide chat bubbles.default false |
close_popupsboolean | Close pop-ups and newsletter overlays.default false |
hide_sticky_elementsboolean | Hide headers, bars and buttons that stay fixed on screen.default false |
disable_animationsboolean | Freeze animations and transitions.default false |
When
wait_forstring | Wait until an element matching this CSS selector is visible. Up to 200 characters. |
delay_msinteger | Extra wait before the capture, in milliseconds. 0 to 5,000.default 0 |
click_selectorstring | Click 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_textstring | Same 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
formatstring | 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 |
qualityinteger | Quality for jpeg and webp. Ignored for png and pdf. 1 to 100.default 80 |
max_widthinteger | Scale the image down to this width. Useful to keep it small for a vision model. 320 to 3,840. |
responsestring | image returns the picture itself. json returns its link, the page details and the attestation. One of image, json.default image |
asyncboolean | 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
httpandhttpspages. A private or local address is refused withurl_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. - A page that is on screen but never finishes loading is still captured, and the answer says so:
page.load_incompleteistrue, and the image shows what was on screen at that moment.page.network_stoppedgives the reason loading was stopped:load_timeout(we waited as long as we wait for a page),visual_ready(the page was displayed and no longer changing) orsoft_byte_cap(the page was displayed and had already downloaded a lot of data). The last two only happen on a screenshot from a country. It isnullwhen the page finished loading.
Every code is on Errors.