Screenshots API

The screenshots endpoint is the core of AllScreenshots. Use it to capture any website as a PNG, JPEG, WebP, or PDF.

Endpoint

POST /v1/screenshots

Request body

{
  "url": "https://example.com",
  "viewport": {
    "width": 1920,
    "height": 1080,
    "deviceScaleFactor": 1
  },
  "format": "png",
  "quality": 80,
  "fullPage": false,
  "delay": 0,
  "waitFor": null,
  "waitUntil": "load",
  "timeout": 30000,
  "darkMode": false,
  "customCss": null,
  "hideSelectors": [],
  "selector": null,
  "blockAds": true,
  "blockCookieBanners": true,
  "blockLevel": "none",
  "stealthMode": false,
  "responseType": "binary"
}

Parameters

Required

Parameter	Type	Description
`url`	string	The URL to capture. Must start with `http://` or `https://`.

Viewport options

Parameter	Type	Default	Description
`viewport.width`	integer	`1920`	Viewport width in pixels (100-4096)
`viewport.height`	integer	`1080`	Viewport height in pixels (100-4096)
`viewport.deviceScaleFactor`	integer	`1`	Device pixel ratio (1-3)
`device`	string	-	Device preset name (alternative to viewport). See devices.

Output options

Parameter	Type	Default	Description
`format`	string	`"png"`	Output format: `png`, `jpeg`, `webp`, or `pdf`
`quality`	integer	`80`	Image quality for JPEG/WebP (1-100)
`fullPage`	boolean	`false`	Capture the full scrollable page
`selector`	string	-	CSS selector to capture a specific element
`responseType`	string	`"binary"`	Response format: `binary`, `base64`, or `url`
`outputs`	array	-	Multi-output extraction. When provided with 2+ items, response is JSON with all outputs.

Timing options

Parameter	Type	Default	Description
`delay`	integer	`0`	Wait time in ms after page load before capture (0-30000)
`waitFor`	string	-	CSS selector to wait for before capturing
`waitUntil`	string	`"load"`	Page load event to wait for: `load`, `domcontentloaded`, `networkidle`
`timeout`	integer	`30000`	Maximum time to wait in ms (1000-60000)

Some pages only reveal their content after an interaction — an "I'm over 18" gate, a consent dialog, a "load more" button. hideSelectors cannot get past these because the content isn't there until you act. actions is an ordered list of steps performed on the live page after it loads (and after ad/cookie blocking) and before the screenshot is taken.

Parameter	Type	Default	Description
`actions`	array	`[]`	Ordered list of interactions to perform before capture (max 25).

Every action has a type plus a few type-specific fields. Two fields are shared by all of them:

Field	Type	Default	Description
`optional`	boolean	`false`	When `false`, a missing target fails the capture (`ACTION_FAILED`). When `true`, the step is skipped — use this for a gate that may already be dismissed.
`timeout`	integer	request `timeout`	Per-action timeout in ms, capped at the request `timeout`.

`type`	Required fields	Description
`click`	`selector`	Click an element
`type`	`selector`, `text`	Type into an input. `clear` (default `true`) replaces the value; `false` appends. `text` up to 10000 chars
`press`	`key`	Press a key (e.g. `"Enter"`). Optional `selector` focuses an element first. `key` up to 50 chars
`hover`	`selector`	Hover over an element (e.g. to open a menu)
`select`	`selector`, `value`	Choose a single option in a native `<select>` by its `value` (not by label or index)
`scroll`	one of `selector` / `y` / `toBottom`	Scroll an element into view, by `y` pixels (negative scrolls up), or to the bottom
`wait`	one of `selector` / `ms` / `networkIdle`	Wait for an element, a fixed delay (`ms`, 0–30000), or until the network is idle

Any selector is limited to 500 characters.

Actions run identically on standard and stealthMode captures, and on async, bulk, and scheduled jobs.

When an action fails

There are two distinct outcomes, and only one of them is affected by optional:

Invalid configuration (a missing required field, more than one of a one-of group like scroll/wait, a value over a limit, or more than 25 actions) is rejected up front with 400 Bad Request. optional does not suppress this — fix the request.
A target that can't be acted on at capture time (the selector never appears, or the step times out) returns 422 ACTION_FAILED. Set optional: true on that step to skip it and continue instead.

Do not put credentials or other secrets in a type action's text — treat actions as part of a logged request. The values are used for the capture but the typed text is redacted from stored logs.

Styling options

Parameter	Type	Default	Description
`darkMode`	boolean	`false`	Emulate `prefers-color-scheme: dark`
`customCss`	string	-	CSS to inject into the page (max 10000 chars)
`hideSelectors`	array	`[]`	CSS selectors to hide (max 50 selectors)

Blocking options

Parameter	Type	Default	Description
`blockAds`	boolean	`true`	Block common ad networks. Set to `false` to disable.
`blockCookieBanners`	boolean	`true`	Block cookie consent banners. Set to `false` to disable.
`blockLevel`	string	`"none"`	Domain blocking level: `none`, `light`, `normal`, `pro`, `pro_plus`, `ultimate`

See Blocking for details on blocking options.

Stealth options

Parameter	Type	Default	Description
`stealthMode`	boolean	`false`	Capture sites protected by Cloudflare, DataDome, and similar bot detection. Pro plan and up. Slower than a standard capture — enable only for URLs that come back blocked.

See Stealth mode for when to use it, expected behavior, and error handling.

Response

The response format depends on the responseType parameter.

Binary response (default)

When responseType: "binary" (or omitted), returns the raw image data with the appropriate content type header:

image/png for PNG format
image/jpeg for JPEG format
image/webp for WebP format
application/pdf for PDF format

Base64 response

When responseType: "base64", returns JSON with the image data encoded as a base64 string:

{
  "url": "https://example.com",
  "format": "png",
  "contentType": "image/png",
  "width": 1920,
  "height": 1080,
  "size": 245678,
  "renderTimeMs": 1234,
  "cached": false,
  "encoding": "base64",
  "data": "iVBORw0KGgo..."
}

URL response

When responseType: "url", the screenshot is stored on the CDN and the response contains a direct download URL:

{
  "url": "https://example.com",
  "format": "png",
  "contentType": "image/png",
  "width": 1920,
  "height": 1080,
  "size": 245678,
  "renderTimeMs": 1234,
  "cached": false,
  "storageUrl": "https://storage.allscreenshots.com/abc123.png",
  "expiresAt": "2025-01-30T12:00:00Z"
}

Response fields

Field	Type	Description
`url`	string	The requested URL
`format`	string	Image format
`contentType`	string	MIME type of the image
`width`	integer	Image width in pixels
`height`	integer	Image height in pixels (null for full page)
`size`	integer	File size in bytes
`renderTimeMs`	integer	Time to render in milliseconds
`cached`	boolean	Whether result was served from cache
`encoding`	string	`"base64"` when `responseType` is `base64`
`data`	string	Base64-encoded image data (only with `responseType: "base64"`)
`storageUrl`	string	CDN URL to download the image (only with `responseType: "url"`)
`expiresAt`	string	ISO 8601 timestamp when the stored file expires (only with `responseType: "url"`)

Multi-output response

When the outputs array is present, the response is always JSON. By default (or with responseType: "base64"), binary outputs are base64-encoded inline:

{
  "url": "https://example.com",
  "outputs": {
    "screenshot": {
      "type": "screenshot",
      "contentType": "image/png",
      "encoding": "base64",
      "data": "iVBOR...",
      "size": 245000
    },
    "markdown": {
      "type": "markdown",
      "contentType": "text/markdown",
      "data": "# Example Domain\n...",
      "size": 1200
    }
  },
  "renderTimeMs": 1250
}

With responseType: "url", each output is stored on the CDN and the response contains URLs instead of inline data:

{
  "url": "https://example.com",
  "outputs": {
    "screenshot": {
      "type": "screenshot",
      "contentType": "image/png",
      "size": 245000,
      "storageUrl": "https://storage.allscreenshots.com/abc123/screenshot.png",
      "expiresAt": "2025-01-30T12:00:00Z"
    },
    "markdown": {
      "type": "markdown",
      "contentType": "text/markdown",
      "size": 1200,
      "storageUrl": "https://storage.allscreenshots.com/abc123/markdown.md",
      "expiresAt": "2025-01-30T12:00:00Z"
    }
  },
  "renderTimeMs": 1250
}

See Multi-output extraction for full documentation.

Examples

Basic screenshot

curl -X POST 'https://api.allscreenshots.com/v1/screenshots' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://github.com"}' \
  --output screenshot.png

Mobile device

curl -X POST 'https://api.allscreenshots.com/v1/screenshots' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://github.com",
    "device": "iphone_15"
  }' \
  --output mobile.png

Full page with dark mode

curl -X POST 'https://api.allscreenshots.com/v1/screenshots' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://github.com",
    "fullPage": true,
    "darkMode": true,
    "blockAds": true,
    "blockCookieBanners": true
  }' \
  --output fullpage-dark.png

Capture specific element

curl -X POST 'https://api.allscreenshots.com/v1/screenshots' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "selector": "h1"
  }' \
  --output header.png

Wait for dynamic content

curl -X POST 'https://api.allscreenshots.com/v1/screenshots' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/dashboard",
    "waitFor": ".chart-loaded",
    "waitUntil": "networkidle",
    "delay": 500
  }' \
  --output dashboard.png

PDF output

curl -X POST 'https://api.allscreenshots.com/v1/screenshots' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/invoice",
    "format": "pdf",
    "fullPage": true
  }' \
  --output invoice.pdf

Multi-output (screenshot + markdown)

curl -X POST 'https://api.allscreenshots.com/v1/screenshots' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/blog/post",
    "outputs": [
      { "type": "screenshot", "fullPage": true },
      { "type": "markdown", "mainContentOnly": true }
    ]
  }'

Error responses

Status	Error	Description
`400`	`VALIDATION_ERROR` / `INVALID_REQUEST`	Invalid request body or parameters
`401`	`API_KEY_REQUIRED`	Missing or invalid API key
`402`	`QUOTA_EXCEEDED`	Monthly quota exceeded
`403`	`CAPABILITY_NOT_AVAILABLE`	A requested feature (e.g. `stealthMode`) isn't on your plan
`408`	`TIMEOUT`	Page load timed out
`422`	`RENDER_FAILED` / `CAPTURE_FAILED`	Screenshot capture failed
`422`	`TARGET_BLOCKED`	The target site blocked the request with bot protection (stealth mode)
`429`	`RATE_LIMITED`	Rate limit exceeded
`502`	`STEALTH_UNAVAILABLE`	Stealth capture is temporarily unavailable — retry shortly
`503`	`SERVICE_BUSY`	Workers are busy — retry after a short delay

Example error response:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "URL must start with http:// or https://",
    "details": {
      "fields": {
        "url": "URL must start with http:// or https://"
      }
    }
  },
  "requestId": "req_abc123"
}

For capturing many URLs or long-running captures, consider using async jobs or bulk processing.

Screenshots