Capturing screenshots

Every example on this page sends a JSON body to POST https://screenshotly.app/api/screenshot with your key in the x-api-key header. Options marked Basic, Growth, or Scale need that plan or higher; see the request reference for every field and bound.

Basic capture

curl --fail-with-body https://screenshotly.app/api/screenshot \
  -X POST \
  -H "x-api-key: $SCREENSHOTLY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com"}' \
  --output screenshot.png

// Node.js 18+ (built-in fetch)
import { writeFile } from 'node:fs/promises';

async function capture(options) {
  const response = await fetch('https://screenshotly.app/api/screenshot', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.SCREENSHOTLY_API_KEY,
      'content-type': 'application/json',
    },
    body: JSON.stringify(options),
  });
  if (!response.ok) {
    throw new Error(`Capture failed: ${response.status} ${await response.text()}`);
  }
  return Buffer.from(await response.arrayBuffer());
}

await writeFile('screenshot.png', await capture({ url: 'https://example.com' }));

import os

import requests


def capture(options: dict) -> bytes:
    response = requests.post(
        "https://screenshotly.app/api/screenshot",
        headers={"x-api-key": os.environ["SCREENSHOTLY_API_KEY"]},
        json=options,
        timeout=60,
    )
    response.raise_for_status()
    return response.content


with open("screenshot.png", "wb") as file:
    file.write(capture({"url": "https://example.com"}))

Without other options you get a 1920 × 1080 PNG of the first screen of the page. The remaining examples show only the JSON body; send it with any of the clients above.

Viewport and devices

Use a device preset or set width and height together:

`device`	Viewport
`desktop`	1920 × 1080
`laptop`	1366 × 768
`tablet`	768 × 1024
`mobile`	375 × 812

{ "url": "https://example.com", "device": "mobile" }

{ "url": "https://example.com", "width": 1440, "height": 900, "deviceScaleFactor": 2 }

device takes precedence: if it is set, width and height are ignored.
width (320–3,840) and height (240–3,840) only apply when both are present.
Presets change the viewport size only, so sites see a narrow window rather than a mobile browser. Set userAgent as well if a site serves different markup to mobile user agents.
deviceScaleFactor (1–3) renders at higher pixel density. At 2, a 1440 × 900 viewport produces a 2880 × 1800 image.

Output formats

`format`	Plan	Notes
`png`	All	Default, lossless
`jpeg`	All	`quality` 0–100
`webp`	All	`quality` 0–100; usually the smallest image
`pdf`	Basic	A4, 1 cm margins, backgrounds printed. Page size and margins are fixed.
`html`	Basic	The rendered DOM after scripts run, as `text/html`
`webm`	Scale	A `videoDuration` of 1–15 seconds at 24 fps

{ "url": "https://example.com", "format": "webp", "quality": 80 }

{ "url": "https://example.com/invoice/4821", "format": "pdf" }

A PDF always contains the whole document across as many A4 pages as needed, so fullPage has no effect on it. For many PDFs, or PDFs of slow pages, use an async job instead of holding the request open.

Full-page and partial captures

{ "url": "https://example.com", "fullPage": true }

{ "url": "https://example.com", "selector": "#pricing" }

{ "url": "https://example.com", "clip": { "x": 0, "y": 0, "width": 1200, "height": 630 } }

fullPage captures the whole scrollable height at the viewport’s width.
selector captures the first matching element’s bounding box. If nothing matches, the request fails with 400 Invalid screenshot options.
clip captures a fixed rectangle in CSS pixels; it wins if you also send selector.

Wait for dynamic content

By default the capture starts when the HTML document has loaded (DOMContentLoaded). Single-page apps, charts, and lazy images often need more time:

{
  "url": "https://example.com/dashboard",
  "waitForSelector": "[data-chart-ready]",
  "delay": 500
}

Option	Use it when
`waitForSelector`	A specific element appears when the page is ready. Waits up to 10 seconds; if the element never appears, the capture continues anyway.
`waitForNetworkIdle`	The page keeps loading data after the document is ready. Waits until network requests stop.
`delay`	You need a fixed pause, for example for an animation, of 0–10,000 ms. Applied after the other waits.
`scroll` (Growth)	Images or sections load only when scrolled into view.

{
  "url": "https://example.com/blog",
  "fullPage": true,
  "scroll": { "enabled": true, "distance": 6000, "speed": 1500 }
}

scroll scrolls the page in steps before capturing (distance 100–50,000 px, default 5,000; speed 100–5,000 px per second, default 500), then returns to the top. Scrolling adds roughly distance ÷ speed seconds to the capture, so keep it short for synchronous requests or use an async job.

Clean up the page

Ads and known elements

blockAds (all plans) blocks common ad networks and hides common ad containers. hideSelectors (Growth) hides up to 100 elements you name:

{
  "url": "https://example.com",
  "blockAds": true,
  "hideSelectors": ["#cookie-consent", ".intercom-lightweight-app"]
}

AI element removal

aiRemoval (Growth) finds overlays you have not named. Screenshotly lists fixed and sticky elements, plus elements whose ID, class, role, or label suggests a banner or widget, asks an AI model to classify them, and removes the matches before capturing.

{
  "url": "https://example.com",
  "aiRemoval": {
    "enabled": true,
    "types": ["cookie-banner", "newsletter", "chat-widget"],
    "confidence": 0.8
  }
}

`types` value	Removes
`cookie-banner`	Cookie and consent banners
`newsletter`	Email sign-up prompts and pop-ups
`chat-widget`	Support chat launchers and windows
`social-overlay`	Social sharing bars and social pop-ups
`ad`	Advertising placements

Omit types, or send an empty list, to consider all five.
confidence (0–1, default 0.8) is the minimum score for removal. Raise it to remove less and avoid false positives; lower it to remove more.
The model is instructed not to select the page’s html, body, main content, navigation, or ordinary controls, but check results on pages you capture often. When you know the selector, hideSelectors is faster and deterministic.

Appearance and locale

{
  "url": "https://example.com",
  "darkMode": true,
  "timezone": "America/New_York",
  "headers": { "Accept-Language": "en-US" }
}

darkMode emulates prefers-color-scheme: dark. It only changes sites that support a dark theme.
timezone takes an IANA name such as Europe/Berlin.
geolocation (Growth) sets the browser’s reported location: { "latitude": 51.5072, "longitude": -0.1276 }. Sites that locate visitors by IP address are not affected; regional IPs are available with proxyRegion (Scale).
headers and cookies are Basic features.

Pass a session with cookies or headers (Basic):

{
  "url": "https://app.example.com/reports/42",
  "cookies": [
    { "name": "session_id", "value": "<session value>", "domain": "app.example.com", "secure": true, "httpOnly": true }
  ],
  "waitForSelector": "#report"
}

A cookie’s domain must be the target host or a parent domain of it. Use a dedicated, low-privilege account; see Security.

Custom JavaScript

javascript (Growth) runs up to 5,000 characters of code in the page after it loads and before the capture, for example to open a tab or remove an element:

{
  "url": "https://example.com",
  "javascript": "document.querySelector('[data-tab=\"annual\"]')?.click();",
  "delay": 300
}

If the script throws, the capture continues without it, so check the output when you change a script.

Handle errors and retries

Retry only when a retry can succeed:

Status	Retry?
`400`, `401`, `403`, `413`	No. Fix the request, key, or plan.
`429`	Yes, after the `Retry-After` header’s seconds, unless the message says the allowance is used up.
`500`, `503`	Yes, a small number of times with backoff.

Node.js

async function captureWithRetry(options, attempts = 3) {
  for (let attempt = 1; ; attempt += 1) {
    const response = await fetch('https://screenshotly.app/api/screenshot', {
      method: 'POST',
      headers: {
        'x-api-key': process.env.SCREENSHOTLY_API_KEY,
        'content-type': 'application/json',
      },
      body: JSON.stringify(options),
    });
    if (response.ok) return Buffer.from(await response.arrayBuffer());

    const retryable = response.status === 429 || response.status >= 500;
    if (!retryable || attempt >= attempts) {
      throw new Error(`Capture failed: ${response.status} ${await response.text()}`);
    }
    const retryAfter = Number(response.headers.get('retry-after'));
    const waitSeconds = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));
  }
}

Failed requests do not consume your capture allowance, but every validated request counts toward per-minute throughput. See Authentication.

Next steps

Using mockups to frame captures in device templates
Async and batch jobs for queued, retryable captures
Webhooks to receive results without polling

Getting Started

API Reference

Guides

Basic capture

Viewport and devices

Output formats

Full-page and partial captures

Wait for dynamic content

Clean up the page

Ads and known elements

AI element removal

Appearance and locale

Custom JavaScript

Handle errors and retries

Next steps

Basic capture

Viewport and devices

Output formats

Full-page and partial captures

Wait for dynamic content

Clean up the page

Ads and known elements

AI element removal

Appearance and locale

Pages behind a login

Custom JavaScript

Handle errors and retries

Next steps