apyhub
Back
▣ MEDIA KIT

Capture Webpage Screenshots in Bulk API

What it does

The Capture Webpage Screenshots in Bulk API renders public webpages in a real Chromium browser and saves each one as a PNG, JPEG or PDF. Send up to 100 URLs in urls and get back count, billed and an items array with one row per page: a screenshotUrl download link, the image width and height, the page title, statusCode and finalUrl, and file details such as bytes and sha256.

Pick a viewport with device (desktop, desktop-hd, laptop, tablet or mobile), or set your own size with viewportWidth and viewportHeight. fullPage captures the whole scrollable page, up to maxHeight (500 to 30,000 px), and truncated tells you when a page was cut. Use waitUntil, delayMs and waitForSelector to wait for late content, hideSelectors and hideCookieBanners to hide overlays, darkMode for the dark color scheme, and elementSelector to capture one element.

Use it to archive pages, take visual QA and monitoring snapshots, or make preview images. Only successful captures are billed. Pages that fail (missing domain, HTTP error, private address) are left out, unless includeFailed is on, in which case they come back as free rows with an error message. If no URL can be captured, the call returns a 400 instead.

POST
Website Screenshot API - Webpage to Image, URL to PNG
https://api.eu.apyhub.com/martin10291/capture-webpage-screenshots-bulk/website-screenshot-api

QUICKSTART

GUIDE

Quickstart

Capture one page as a full-page PNG with the default desktop viewport.

curl -X POST "https://api.eu.apyhub.com/martin10291/capture-webpage-screenshots-bulk" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://apyhub.com"], "format": "png"}'

What you'll get back

Returns a JSON object with count, billed and an items array. Each item is one captured page with its screenshotUrl download link, size and page details.

{
  "billed": 1,
  "count": 1,
  "items": [
    {
      "url": "https://example.com",
      "finalUrl": "https://example.com/",
      "statusCode": 200,
      "title": "Example Domain",
      "device": "desktop",
      "deviceScaleFactor": 1,
      "format": "png",
      "fullPage": true,
      "width": 1366,
      "height": 787,
      "pageHeight": 787,
      "truncated": false,
      "bytes": 72342,
      "key": "shot-example.com-327c3fda87.png",
      "screenshotUrl": "https://radarbg.com/m/f/k1jn1VL26vBRNLo2e/shot-example.com-327c3fda87.png?s=3kvS8fVIQ43HitqOrL5D",
      "sha256": "582c8efb49c61cbee5fc044d22ce5b843133dc6cefddb89ad10cef3d5d34ef76",
      "contentHash": "43338e32beb5871d10be1ac1",
      "loadTimeMs": 959,
      "takenAt": "2026-11-17T10:19:57Z",
      "error": null,
      "warning": null
    }
  ]
}
TRY ITLIVE · 100 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.
body*
urls*
Public pages to capture, one URL per entry. Full http/https URLs or bare domains. Private and local addresses are rejected; duplicates are captured once.
Viewport preset: desktop 1366x768, desktop-hd 1920x1080, laptop 1280x800, tablet 820x1180 (2x), mobile 390x844 (3x).
Output file format.
Extra wait after loading, before the capture, in milliseconds.

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

ParameterTypeDescription
urlsString ArrayRequired. 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.
deviceENUMViewport preset. Allowed values: desktop (1366x768), desktop-hd (1920x1080), laptop (1280x800), tablet (820x1180, 2x), mobile (390x844, 3x, touch). Default: desktop.
formatENUMOutput file format. Allowed values: png, jpeg, pdf. Default: png.
fullPageBooleanCapture the whole scrollable page up to maxHeight. false captures only the viewport. Default: true.
maxHeightIntegerFull-page captures are cut at this height in pixels; truncated is true when this happens. Range: 500 to 30000.
viewportWidthIntegerOverrides the preset width. Range: 320 to 3840, or 0 to use the preset.
viewportHeightIntegerOverrides the preset height. Range: 240 to 2160, or 0 to use the preset.
waitUntilENUMWhen the page counts as loaded. Allowed values: load, domcontentloaded (fastest), networkidle (no network for 500 ms, best for heavy JavaScript apps). Default: load.
delayMsIntegerExtra wait after loading, before the capture, for animations, charts and fonts. Range: 0 to 30000.
waitForSelectorStringCSS selector to wait for before the capture, e.g. #main or .chart-ready.
timeoutSecsIntegerGive 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.
elementSelectorStringCSS 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.
hideSelectorsString ArrayCSS selectors to hide before the capture, e.g. chat widgets, sticky headers or ads. Max 100 items.
hideCookieBannersBooleanHide common cookie and consent popups with CSS. Nothing is clicked or accepted.
scrollToLoadImagesBooleanFor full-page captures, scroll through the page first so lazy-loaded images appear.
darkModeBooleanAsk the page for its dark color scheme (prefers-color-scheme: dark).
jpegQualityIntegerJPEG quality; lower gives smaller files. Only used when format is jpeg. Range: 10 to 100.
includeFailedBooleanAlso return a row for each page that failed, with an error message. Failed rows are not billed. Default: false.
maxUrlsIntegerHard 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.

ParameterTypeDescription
countIntegerNumber of rows in items.
billedIntegerNumber of successful captures charged for this call. Failed rows are not counted.
items[].urlStringThe URL as it was captured, with the scheme added to bare domains.
items[].finalUrlStringURL after redirects. null when the page could not be reached.
items[].statusCodeIntegerHTTP status of the page. null when the page could not be reached.
items[].titleStringPage title. null for failed rows.
items[].deviceStringDevice preset used.
items[].formatENUMAllowed values: png, jpeg, pdf. File format produced.
items[].fullPageBooleanWhether a full-page capture was requested.
items[].takenAtStringCapture time, ISO 8601 UTC.
items[].errorStringnull when the capture succeeded; otherwise why it failed, e.g. HTTP 404 or a browser network error.
items[].warningStringNote about a partial capture, e.g. a page that hit timeoutSecs. null when there is none.
items[].screenshotUrlStringDownload link for the file. null for failed rows.
items[].keyStringFile name, e.g. shot-example.com-327c3fda87.png. null for failed rows.
items[].widthIntegerWidth of the file in pixels. Successful rows only.
items[].heightIntegerHeight of the file in pixels. Successful rows only.
items[].pageHeightIntegerFull scroll height of the page in pixels. Successful rows only.
items[].truncatedBooleantrue when a full-page capture was cut at maxHeight. Successful rows only.
items[].deviceScaleFactorNumberPixel ratio used (1, 2 or 3). Successful rows only.
items[].bytesIntegerFile size in bytes. Successful rows only.
items[].sha256StringSHA-256 hash of the file. Successful rows only.
items[].contentHashStringShort hash of the page content, useful to spot pages that did not change. Successful rows only.
items[].loadTimeMsIntegerTime 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 100 urls or hideSelectors, 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 includeFailed is true.
  • The order of items may differ from the order of urls. Match rows by url.
  • Each page takes a few seconds; large batches and long delayMs or timeoutSecs values make the call slower.
▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.