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)

url

string

required

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

name

string

Optional name for the screenshot (max 100 characters).

Capture options

Pass these inside the options object in the request body.

options.format

string

default:"png"

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

options.viewport_width

integer

default:"1280"

Viewport width in pixels (100–5000).

options.viewport_height

integer

default:"1024"

Viewport height in pixels (100–5000).

options.full_page

boolean

default:"false"

Capture the full scrollable page instead of just the viewport.

options.image_quality

integer

default:"80"

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

options.device_scale_factor

number

default:"1"

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

options.viewport_mobile

boolean

default:"false"

Emulate a mobile device viewport.

options.viewport_has_touch

boolean

default:"false"

Enable touch event support.

options.viewport_landscape

boolean

default:"false"

Use landscape orientation.

options.block_ads

boolean

default:"false"

Block advertisements on the page.

Block cookie consent banners.

options.block_chats

boolean

default:"false"

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

options.selector

string

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

options.selector_scroll_into_view

boolean

default:"true"

Automatically scroll the selected element into view before capturing.

options.error_on_selector_not_found

boolean

default:"false"

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

options.wait_for_selector

string

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

options.delay

integer

default:"0"

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

options.timeout

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

options.wait_until

string

default:"load"

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

options.response_type

string

default:"by_format"

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

options.dark_mode

boolean

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

options.omit_background

boolean

default:"false"

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

options.full_page_scroll

boolean

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

options.full_page_scroll_delay

integer

default:"400"

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

options.full_page_scroll_by

integer

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

options.full_page_max_height

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