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 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)

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

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 has 2 or more items, 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 '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

Multi-output (screenshot + markdown)

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/blog/post",
    "outputs": [
      { "type": "screenshot", "fullPage": true },
      { "type": "markdown", "mainContentOnly": true }
    ]
  }'

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