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": false,
  "blockCookieBanners": false,
  "blockLevel": "none",
  "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 type: `binary` or `json`

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)

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	`false`	Block common ad networks
`blockCookieBanners`	boolean	`false`	Block cookie consent banners
`blockLevel`	string	`"none"`	Domain blocking level: `none`, `light`, `normal`, `pro`, `pro_plus`, `ultimate`

See Blocking for details on blocking options.

Response

Binary response (default)

Returns the image data with appropriate content type:

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

JSON response

When responseType: "json":

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

Field	Type	Description
`url`	string	URL to download the screenshot
`expiresAt`	string	ISO 8601 timestamp when the URL expires
`size`	integer	File size in bytes
`width`	integer	Image width in pixels
`height`	integer	Image height in pixels (null for full page)
`format`	string	Image format
`renderTime`	integer	Time to render in milliseconds
`cached`	boolean	Whether result was served from cache

Examples

Basic screenshot

curl -X POST 'https://api.allscreenshots.com/v1/screenshots' \
  -H 'Authorization: Bearer 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 'Authorization: Bearer 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 'Authorization: Bearer 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 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://github.com",
    "selector": "header.AppHeader"
  }' \
  --output header.png

Wait for dynamic content

curl -X POST 'https://api.allscreenshots.com/v1/screenshots' \
  -H 'Authorization: Bearer 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 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/invoice",
    "format": "pdf",
    "fullPage": true
  }' \
  --output invoice.pdf

Error responses

Status	Error	Description
`400`	`invalid_request`	Invalid request parameters
`401`	`unauthorized`	Missing or invalid API key
`402`	`quota_exceeded`	Monthly quota exceeded
`408`	`timeout`	Page load timed out
`422`	`capture_failed`	Screenshot capture failed
`429`	`rate_limit_exceeded`	Rate limit exceeded

Example error response:

{
  "error": "invalid_request",
  "message": "URL must start with http:// or https://",
  "field": "url"
}

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

Screenshots

On this page