Capture screenshots and PDFs

Capture a page as a PNG, JPEG or WebP screenshot with screenshot=true, or print it to PDF with response_format=pdf on the chromium engine.

Use this when you need the page as it looks rather than as it reads: visual regression checks, archiving a page as evidence, a thumbnail for a link preview, or a printable PDF of an invoice or report. Set screenshot: true for an image, or response_format: "pdf" for a document.

Both need an engine with a rasteriser. Screenshots and PDFs work on chromium (engine: "chromium"). The fetch engine, obscura (what js_render: true selects) and mode: "auto" cannot draw a page, and the request is refused before anything is spent.

Minimal request

curl https://api.spicrawl.com/v1/scrape \
  -H "Authorization: Bearer $SPICRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/products/42", "engine": "chromium", "screenshot": true, "screenshot_fullpage": true}'

What comes back

screenshot: true always returns the JSON envelope. The rendered page is under content and each image is an object in screenshots:

{
  "url": "https://example.com/products/42",
  "final_url": "https://example.com/products/42",
  "status": 200,
  "content": "<!doctype html><html>…",
  "engine": "chromium",
  "credits": 8,
  "screenshots": [
    {
      "label": "final",
      "encoding": "base64",
      "data": "iVBORw0KGgoAAAANSUhEUgAA…",
      "size_bytes": 184223,
      "format": "png",
      "width": 800,
      "height": 3412
    }
  ],
  "warnings": []
}

The top-level screenshot has label: "final". Screenshots taken by a screenshot browser action carry that step's label.
width and height are omitted when the engine did not measure them.
If you asked for another response_format (for example markdown), the response is still the envelope, with content in the format you asked for, and X-Warning: FORMAT_COERCED.
screenshots lists delivered images only. An image the engine failed to deliver is reported in warnings, and the request is charged 0 credits even though the page comes back.

With response_format: "pdf", the body is the PDF bytes (Content-Type: application/pdf), not the envelope. Save it as a file. Setting screenshot, extract, autoparse, links, ai_extract or network_capture at the same time switches the response to the envelope with X-Warning: FORMAT_COERCED, so leave them off for a PDF.

curl https://api.spicrawl.com/v1/scrape \
  -H "Authorization: Bearer $SPICRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/invoices/2026-09", "engine": "chromium", "response_format": "pdf"}' \
  -o invoice.pdf

The CLI refuses to write PDF bytes to a terminal: pass -o FILE, or --json to get the output base64-encoded.

Options

Field	Default	Effect
`screenshot`	`false`	Capture an image. Forces the JSON envelope.
`screenshot_fullpage`	`false`	Capture the whole scrollable page instead of the viewport. Requires `screenshot: true`. Cannot be combined with `screenshot_selector`.
`screenshot_selector`	none	CSS selector of one element to capture. Requires `screenshot: true`. Cannot be combined with `screenshot_fullpage`.
`screenshot_format`	engine default (`png`)	`png`, `jpeg`, `jpg` or `webp`.
`screenshot_quality`	`0` (engine default)	0–100, used by `jpeg` and `webp`. A value above 0 requires `screenshot: true`.
`response_format`	`html`	`pdf` returns a browser-printed PDF. Needs `engine: "chromium"`.
`headless`	deployment default (headless)	`false` runs Chromium with a real display: a 1920x1080 screen instead of 800x600. Chromium only.
`wait`, `wait_for`	none	Let late content load before capture. See JavaScript rendering.
`block_resources`	see below	Resource classes the browser does not load.

screenshot_format is not validated by the API. An unrecognised value (for example "gif") is not a 400: the engine silently uses its default, PNG. Check the format field on each returned screenshot to see what you got.

Images and fonts load by default here. Browser renders normally block images and fonts. That default is skipped when you set screenshot or response_format: "pdf", because a capture without them would not show the real page. An explicit block_resources list still applies, so leave it unset unless you want those resources missing from the capture.

Failure modes

Code	HTTP	What to do
`ERR::REQUEST::CAPABILITY_UNSUPPORTED`	400	The selected engine cannot rasterise: fetch, `obscura`, `js_render: true` without a pin, or `mode: "auto"`. Set `engine: "chromium"`. 0 credits.
`ERR::REQUEST::INCOMPATIBLE_FLAGS`	400	`screenshot_fullpage` or `screenshot_selector` without `screenshot: true`, or both at once.
`ERR::AUTH::ENGINE_NOT_ENTITLED`	403	Your plan does not include `chromium`. Upgrade to a plan that includes it. 0 credits.
`ERR::ENGINE::UNAVAILABLE`	503	The engine is not deployed or has no free slot. Retry after `Retry-After`.
`ERR::ENGINE::RENDER_FAILED`	502	The page could not be rendered. Retry once; if it repeats, try `wait_for` on a stable selector.

A missing element for screenshot_selector, or any other capture the engine could not deliver, is not an error: the page is returned, the image is absent from screenshots, warnings says why, and the charge is 0.

Cost

A screenshot or PDF adds no credits on top of the engine price. You pay for the engine that ran: chromium is 8 credits.

Failures, undelivered screenshots and non-billable target statuses cost 0. A repeat of the same request inside the cache window is served from the cache at 0 credits, image included. X-Credits-Charged is what was billed. See Credits.

Browser actions to screenshot the page between steps
JavaScript rendering for wait and wait_for
Anti-bot when the page behind the screenshot is protected
Caching