Skip to main content

​
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

HeaderRequiredDescription
X-API-KeyYesYour API key
Content-TypeYes (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.
​
options.block_cookie_banners
boolean
default:"false"
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).
​
options.navigation_timeout
integer
default:"30000"
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

StatusCodeDescription
401missing_api_keyNo API key provided
401invalid_api_keyInvalid or revoked API key
402usage_limit_exceededMonthly screenshot limit reached
422invalid_optionsValidation failed — check the details field
422invalid_urlURL format is invalid
422selector_not_foundSpecified CSS selector not found on page
429rate_limit_exceededToo many requests per minute
500render_failedScreenshot capture failed
502host_errorCould not reach the target URL
503service_unavailableScreenshot service is starting up
504navigation_timeoutPage 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"
    }
  }'