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)

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

On this page