POST /v1/screenshot opens a URL in a fresh browser and returns an image of it: the visible part, the whole page, or one element. The response body is the image itself.

Request

curl -X POST https://api.boxline.dev/v1/screenshot \  -H "x-api-key: $BOXLINE_API_KEY" \  -H "content-type: application/json" \  -d '{"url": "https://example.com", "fullPage": true}' \  -o page.png

import { writeFile } from "node:fs/promises";const png = await bx.screenshot("https://example.com", { fullPage: true });await writeFile("page.png", png);

png = bx.screenshot("https://example.com", full_page=True)with open("page.png", "wb") as f:    f.write(png)

boxline screenshot https://example.com -o page.png --full-page

Field	Default	Description
`url`	required	The page.
`fullPage`	`false`	The whole page, not only the part that fits the viewport.
`format`	`"png"`	`"png"` or `"jpeg"`.
`quality`	`80`	JPEG quality, 1 to 100. Ignored for PNG.
`selector`	none	Only the first element that matches this selector: CSS, or any Playwright selector such as `text=Pricing`.
`viewport`	1280×720	`{ width, height }`, from 320×240 to 3840×2160.

It also takes the options every web API shares:

Field	Default	Description
`waitUntil`	`"load"`	When the page counts as loaded: `"load"`, `"domcontentloaded"`, `"networkidle"` (no network traffic for a moment) or `"commit"`.
`delayMs`	`0`	Extra wait after the page loads, up to 10,000 ms. Useful for pages that draw late.
`timeoutMs`	`30000`	How long to wait for the page, from 1,000 to 120,000 ms.
`proxy`	none	Load the page through a residential, datacenter or your own proxy, e.g. `{ "type": "residential", "country": "FR" }`. The IP changes with every request unless you ask for `"ip": "sticky"`. See Proxies.
`browser`	standard	The page’s clock and language, e.g. `{ "mode": "realistic" }` to follow the proxy’s country, or `{ "locale": "fr-FR", "timezone": "Europe/Paris" }`. See Browser mode.
`blockAds`	`false`	Refuse requests to ad and tracker sites while the page loads: faster, with less clutter, and no proxy data spent on them. See Ad and cookie-banner blocking.

Response

The body is the image (image/png or image/jpeg). These headers describe the page:

Header	What it holds
`x-final-url`	The address after redirects (URI-encoded).
`x-page-status`	The page’s HTTP status, or empty when unknown.
`x-page-title`	The page title, URI-encoded, at most 200 characters.
`x-page-captcha`	The kind of CAPTCHA that was waiting for a person, or empty. See CAPTCHAs.
`x-render-ms`	How long it took, in milliseconds.

Browsers can read these headers too, so a web app can show them. The SDKs return only the image bytes.

Errors

Status and code	What it means
`502 page_unreachable`	The page could not be loaded. The message names the host and Chrome’s reason, e.g. `could not load example.com: ERR_NAME_NOT_RESOLVED`. When Chrome’s reason is a generic one, the message adds the real one in words, e.g. `(the name does not resolve (DNS))`. See why a page did not load.
`504 page_timeout`	The page did not finish loading within `timeoutMs`. Try a longer time or another `waitUntil`.
`402 feature_not_in_plan`	Your plan does not include this API, or the kind of proxy you asked for.
`429 rate_limited`	Too many requests. Wait for the seconds in `Retry-After`. See Rate limits.

To take screenshots in the middle of your own work, use the screenshot action in a session instead. Every field is in the API reference: Take a screenshot.

These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.