Capture screenshot

Endpoint

POST https://api.screenshotly.dev/v1/capture
GET  https://api.screenshotly.dev/v1/capture

The POST method accepts parameters in the request body. The GET method accepts all parameters as query strings and always returns a binary image.

Headers

Header	Required	Description
`X-API-Key`	Yes	Your API key
`Content-Type`	Yes (POST)	`application/json`

Request body (POST)

string

required

The URL of the webpage to capture. Must be a valid URL.

string

Optional name for the screenshot (max 100 characters).

Capture options

Pass these inside the options object in the request body.

string

default:"png"

Output format. Options: png, jpeg, webp, pdf.

integer

default:"1280"

Viewport width in pixels (100–5000).

integer

default:"1024"

Viewport height in pixels (100–5000).

boolean

default:"false"

Capture the full scrollable page instead of just the viewport.

integer

default:"80"

Image quality for JPEG, WebP, and PDF (0–100). Ignored for PNG.

number

default:"1"

Device pixel ratio (1–3). Use 2 for retina-quality screenshots.

boolean

default:"false"

Emulate a mobile device viewport.

boolean

default:"false"

Enable touch event support.

boolean

default:"false"

Use landscape orientation.

boolean

default:"false"

Block advertisements on the page.

Block cookie consent banners.

boolean

default:"false"

Block chat widgets (e.g., Intercom, Drift).

string

CSS selector of a specific element to capture instead of the full page (max 255 characters).

boolean

default:"true"

Automatically scroll the selected element into view before capturing.

boolean

default:"false"

Return an error if the specified selector is not found on the page.

string

CSS selector to wait for before capturing (max 255 characters). The capture starts once this element exists in the DOM.

integer

default:"0"

Milliseconds to wait after page load before capturing (0–10000).

integer

default:"60000"

Maximum time in milliseconds to wait for the page and screenshot process (1000–90000).

Maximum time in milliseconds to wait for page navigation (1000–30000).

string

default:"load"

When to consider navigation complete. Options: load, domcontentloaded, networkidle0, networkidle2. Can also be an array of values.

string

default:"by_format"

Controls the response format. Options: by_format, json, empty.

boolean

Emulate dark color scheme (prefers-color-scheme: dark).

boolean

default:"false"

Remove the default white background for transparent captures (PNG and WebP only).

boolean

Scroll through the page before capturing. Useful for triggering lazy-loaded content.

integer

default:"400"

Milliseconds to wait between scroll steps (0–5000).

integer

Number of pixels to scroll per step (0–5000).

integer

Maximum height in pixels for full-page captures (0–50000).

Response

The response format depends on the response_type option.

`response_type: "by_format"` (default)

Returns the screenshot as binary data with the appropriate Content-Type header (e.g., image/png, image/jpeg, application/pdf). For POST requests, a Content-Disposition: attachment header is also included.

`response_type: "json"`

Returns 201 Created with a JSON response:

{
  "success": true,
  "data": {
    "id": "67b8a1c2d3e4f5a6b7c8d9e0",
    "url": "https://example.com",
    "image_url": "https://cdn.screenshotly.dev/screenshots/67b8a1c2d3e4f5a6b7c8d9e0.png",
    "status": "completed",
    "metadata": {
      "file_size": 245760,
      "format": "png",
      "dimensions": {
        "width": 1280,
        "height": 1024
      }
    },
    "created_at": "2025-05-14T10:30:00.000Z"
  },
  "remaining_credits": 99
}

`response_type: "empty"`

Returns 200 OK with an empty body. Useful for fire-and-forget captures.

Error responses

Status	Code	Description
401	`missing_api_key`	No API key provided
401	`invalid_api_key`	Invalid or revoked API key
402	`usage_limit_exceeded`	Monthly screenshot limit reached
422	`invalid_options`	Validation failed — check the `details` field
422	`invalid_url`	URL format is invalid
422	`selector_not_found`	Specified CSS selector not found on page
429	`rate_limit_exceeded`	Too many requests per minute
500	`render_failed`	Screenshot capture failed
502	`host_error`	Could not reach the target URL
503	`service_unavailable`	Screenshot service is starting up
504	`navigation_timeout`	Page navigation timed out

See error codes for the full error response format.

Examples

Basic capture (binary response)

curl -X POST https://api.screenshotly.dev/v1/capture \
  -H "X-API-Key: $SCREENSHOTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}' \
  --output screenshot.png

GET request (binary response)

curl "https://api.screenshotly.dev/v1/capture?url=https://example.com&api_key=$SCREENSHOTLY_API_KEY" \
  --output screenshot.png

Full-page JPEG with custom viewport (JSON response)

curl -X POST https://api.screenshotly.dev/v1/capture \
  -H "X-API-Key: $SCREENSHOTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "options": {
      "format": "jpeg",
      "image_quality": 85,
      "full_page": true,
      "viewport_width": 1440,
      "viewport_height": 900,
      "response_type": "json"
    }
  }'

Mobile device with dark mode

curl -X POST https://api.screenshotly.dev/v1/capture \
  -H "X-API-Key: $SCREENSHOTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "options": {
      "viewport_width": 390,
      "viewport_height": 844,
      "device_scale_factor": 3,
      "viewport_mobile": true,
      "dark_mode": true,
      "response_type": "json"
    }
  }'

Capture specific element with ad blocking

curl -X POST https://api.screenshotly.dev/v1/capture \
  -H "X-API-Key: $SCREENSHOTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "options": {
      "selector": "#main-content",
      "block_ads": true,
      "block_cookie_banners": true,
      "response_type": "json"
    }
  }'

Overview

Capture

Screenshots

Resources

Endpoint

Headers

Request body (POST)

Capture options

Response

`response_type: "by_format"` (default)

`response_type: "json"`

`response_type: "empty"`

Error responses

Examples

Basic capture (binary response)

GET request (binary response)

Full-page JPEG with custom viewport (JSON response)

Mobile device with dark mode

Capture specific element with ad blocking

​Endpoint

​Headers

​Request body (POST)

​Capture options

​Response

​response_type: "by_format" (default)

​response_type: "json"

​response_type: "empty"

​Error responses

​Examples

​Basic capture (binary response)

​GET request (binary response)

​Full-page JPEG with custom viewport (JSON response)

​Mobile device with dark mode

​Capture specific element with ad blocking

Endpoint

Headers

Request body (POST)

Capture options

Response

`response_type: "by_format"` (default)

`response_type: "json"`

`response_type: "empty"`

Error responses

Examples

Basic capture (binary response)

GET request (binary response)

Full-page JPEG with custom viewport (JSON response)

Mobile device with dark mode

Capture specific element with ad blocking