About this endpoint
What it does
Captures one or more public webpages in a real Chromium browser as PNG, JPEG or PDF files. Returns a JSON object with one row per captured page, each with a download link and details about the page and the file.
Request Body
| Parameter | Type | Description |
|---|---|---|
| urls | String Array | Required. Public pages to capture, one URL per entry. Full http/https URLs or bare domains like example.com. Private and local addresses are rejected. Duplicate URLs are captured once. Min 1 item, max 100 items. |
| device | ENUM | Viewport preset. Allowed values: desktop (1366x768), desktop-hd (1920x1080), laptop (1280x800), tablet (820x1180, 2x), mobile (390x844, 3x, touch). Default: desktop. |
| format | ENUM | Output file format. Allowed values: png, jpeg, pdf. Default: png. |
| fullPage | Boolean | Capture the whole scrollable page up to maxHeight. false captures only the viewport. Default: true. |
| maxHeight | Integer | Full-page captures are cut at this height in pixels; truncated is true when this happens. Range: 500 to 30000. |
| viewportWidth | Integer | Overrides the preset width. Range: 320 to 3840, or 0 to use the preset. |
| viewportHeight | Integer | Overrides the preset height. Range: 240 to 2160, or 0 to use the preset. |
| waitUntil | ENUM | When the page counts as loaded. Allowed values: load, domcontentloaded (fastest), networkidle (no network for 500 ms, best for heavy JavaScript apps). Default: load. |
| delayMs | Integer | Extra wait after loading, before the capture, for animations, charts and fonts. Range: 0 to 30000. |
| waitForSelector | String | CSS selector to wait for before the capture, e.g. #main or .chart-ready. |
| timeoutSecs | Integer | Give up on a page that does not load in this many seconds. A partly loaded page is still captured, with a warning. Range: 5 to 120. |
| elementSelector | String | CSS selector of one element to capture instead of the page, e.g. header or #pricing. The first match is captured (PNG and JPEG). Returns 400 if no element matches. |
| hideSelectors | String Array | CSS selectors to hide before the capture, e.g. chat widgets, sticky headers or ads. Max 100 items. |
| hideCookieBanners | Boolean | Hide common cookie and consent popups with CSS. Nothing is clicked or accepted. |
| scrollToLoadImages | Boolean | For full-page captures, scroll through the page first so lazy-loaded images appear. |
| darkMode | Boolean | Ask the page for its dark color scheme (prefers-color-scheme: dark). |
| jpegQuality | Integer | JPEG quality; lower gives smaller files. Only used when format is jpeg. Range: 10 to 100. |
| includeFailed | Boolean | Also return a row for each page that failed, with an error message. Failed rows are not billed. Default: false. |
| maxUrls | Integer | Hard cap on how many URLs are captured in this call; extra URLs are skipped. Range: 1 to 2000. |
Response
Returns a JSON object with count, billed and an items array. Each item is one page: a captured page has a screenshotUrl and file details, and a failed page (only with includeFailed: true) has error set and its file fields left out.
| Parameter | Type | Description |
|---|---|---|
| count | Integer | Number of rows in items. |
| billed | Integer | Number of successful captures charged for this call. Failed rows are not counted. |
| items[].url | String | The URL as it was captured, with the scheme added to bare domains. |
| items[].finalUrl | String | URL after redirects. null when the page could not be reached. |
| items[].statusCode | Integer | HTTP status of the page. null when the page could not be reached. |
| items[].title | String | Page title. null for failed rows. |
| items[].device | String | Device preset used. |
| items[].format | ENUM | Allowed values: png, jpeg, pdf. File format produced. |
| items[].fullPage | Boolean | Whether a full-page capture was requested. |
| items[].takenAt | String | Capture time, ISO 8601 UTC. |
| items[].error | String | null when the capture succeeded; otherwise why it failed, e.g. HTTP 404 or a browser network error. |
| items[].warning | String | Note about a partial capture, e.g. a page that hit timeoutSecs. null when there is none. |
| items[].screenshotUrl | String | Download link for the file. null for failed rows. |
| items[].key | String | File name, e.g. shot-example.com-327c3fda87.png. null for failed rows. |
| items[].width | Integer | Width of the file in pixels. Successful rows only. |
| items[].height | Integer | Height of the file in pixels. Successful rows only. |
| items[].pageHeight | Integer | Full scroll height of the page in pixels. Successful rows only. |
| items[].truncated | Boolean | true when a full-page capture was cut at maxHeight. Successful rows only. |
| items[].deviceScaleFactor | Number | Pixel ratio used (1, 2 or 3). Successful rows only. |
| items[].bytes | Integer | File size in bytes. Successful rows only. |
| items[].sha256 | String | SHA-256 hash of the file. Successful rows only. |
| items[].contentHash | String | Short hash of the page content, useful to spot pages that did not change. Successful rows only. |
| items[].loadTimeMs | Integer | Time the page took to load, in milliseconds. Successful rows only. |
Notes
- Invalid input returns 400 with a message naming the field and its allowed range, and nothing is billed. That covers a missing or empty
urls, more than 100urlsorhideSelectors, values out of range, and unknown enum values. - If none of the URLs can be captured (missing domain, HTTP error, private address), the call returns 400 with the reason. If some URLs succeed, the failed ones are left out, or come back as free rows when
includeFailedistrue. - The order of
itemsmay differ from the order ofurls. Match rows byurl. - Each page takes a few seconds; large batches and long
delayMsortimeoutSecsvalues make the call slower.


