Screenshot Options

This is the complete reference for all parameters you can pass when capturing a screenshot. Parameters work with both the sync (GET /capture) and async (POST /screenshots) endpoints. For endpoint details, see Screenshots.

Note

Some parameters are only available on certain plans. If you use a feature not included in your plan, the API returns a 422 error. See the Feature Availability table for details.

Source

Every screenshot needs a source — what to capture. You have three options: a live URL, raw HTML, or Markdown. Provide exactly one of these.

Parameter	Type	Description
`url`	string	The URL to capture. Must start with `http://` or `https://`. Max 2,048 characters.
`html`	string	Raw HTML to render as a screenshot. The HTML is loaded directly in the browser — no live URL needed. Great for generating images from templates, invoices, or reports. Max 500,000 characters.
`markdown`	string	Markdown content to render. Converted to styled HTML automatically with clean typography and table formatting. Max 500,000 characters.

Example: Capture a URL

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com" \
  -o screenshot.png

Example: Render HTML

curl -X POST https://api.screenshotrun.com/v1/screenshots/capture \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<html><body style=\"padding:40px;font-family:sans-serif\"><h1>Hello World</h1><p>Rendered from raw HTML</p></body></html>",
    "width": 800,
    "height": 600
  }' \
  -o screenshot.png

Example: Render Markdown

curl -X POST https://api.screenshotrun.com/v1/screenshots/capture \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Monthly Report\n\n## Key Metrics\n\n| Metric | Value |\n|--------|-------|\n| Users | 1,234 |\n| Revenue | $5,678 |\n\n> Data as of June 2026",
    "width": 800,
    "height": 600
  }' \
  -o report.png

Viewport & Device

Control the browser window size and device emulation. By default, screenshots use a 1280×800 desktop viewport. You can set a custom size, pick a device preset, or enable retina resolution.

Parameter	Type	Default	Description
`width`	integer	1280	Viewport width in pixels. Range: 320–3840.
`height`	integer	800	Viewport height in pixels. Range: 200–2160.
`device`	string	`desktop`	Device preset: `desktop` (1280×800), `mobile` (375×812, iPhone user-agent), or `tablet` (768×1024, iPad user-agent). Sets both viewport size and User-Agent string.
`retina`	boolean	`false`	Capture at 2× resolution for sharper images (Retina display). The output image will be twice the viewport dimensions.

Example: Mobile screenshot

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "device": "mobile",
    "format": "png"
  }'

Example: Custom viewport

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&width=1920&height=1080&retina=true" \
  -o screenshot.png

Image Output

Choose the output format and control image quality. ScreenshotRun supports six formats, each suited for different use cases.

Parameter	Type	Default	Description
`format`	string	`png`	Output format: `png`, `jpeg`, `webp`, `avif`, `tiff`, or `pdf`.
`quality`	integer	80	Compression quality for JPEG, WebP, and AVIF. Range: 1–100. Higher values mean better quality but larger file sizes. Has no effect on PNG or TIFF.
`resize_width`	integer	—	Resize the output image to this width (16–3840). Aspect ratio is preserved. The image will not be enlarged beyond its original size.
`resize_height`	integer	—	Resize the output image to this height (16–2160). Aspect ratio is preserved.

Note

When both resize_width and resize_height are provided, the image fits inside the given dimensions while maintaining aspect ratio. Resize only applies to image formats, not PDF.

Which format to choose?

PNG — lossless quality, best for screenshots with text and sharp edges. Larger file sizes.
WebP — modern format with excellent compression. 30–50% smaller than PNG at similar quality. Best all-around choice.
JPEG — smallest files for photographic content. May show artifacts on text and sharp edges.
AVIF — next-generation format with the best compression ratio. Not yet supported by all browsers.
TIFF — archival format for maximum quality. Very large files.
PDF — document format. See PDF Options below.

Example: WebP thumbnail

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&format=webp&quality=60&resize_width=320" \
  -o thumbnail.webp

Full Page

By default, the API captures only the visible viewport (what you would see in the browser without scrolling). To capture the entire scrollable page from top to bottom, set full_page=true.

Parameter	Type	Default	Description
`full_page`	boolean	`false`	Capture the entire scrollable page instead of just the viewport.

Example

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "full_page": true,
    "format": "webp"
  }'

Timing & Page Loading

Some pages need extra time to load. Maybe they use JavaScript to render content (like React or Vue apps), load images lazily, or have animations that need to finish. These parameters let you control when exactly the screenshot is taken.

Parameter	Type	Default	Description
`delay`	integer	0	Wait this many seconds after the page loads before capturing. Range: 0–10. Useful for animations or lazy-loaded images.
`timeout`	integer	30	Maximum time in seconds to wait for the page to load. Range: 5–60. If the page doesn't load within this time, the screenshot fails with a `TIMEOUT` error.
`wait_for_selector`	string	—	CSS selector to wait for before capturing. The API waits until this element appears in the DOM (up to 10 seconds). Perfect for SPAs and dynamically loaded content. Max 500 characters.

Example: Wait for a chart to render

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/dashboard",
    "wait_for_selector": ".chart-container canvas",
    "delay": 1
  }'

This first waits for the chart canvas to appear, then waits an extra second for the animation to finish.

Element Selection & Interaction

Instead of capturing the full page, you can target a specific element. You can also click elements, scroll to sections, or hide distracting parts of the page before the screenshot is taken.

Parameter	Type	Description
`selector`	string	CSS selector of a specific element to capture. Only that element is cropped and returned. Max 500 characters.
`click_selector`	string	CSS selector of an element to click before capturing. Useful for dismissing modals, expanding content, or accepting cookie consent. Max 500 characters.
`scroll_to`	string	CSS selector of an element to scroll into view before capturing. Combine with `selector` to capture a specific section. Max 500 characters.
`hide_selectors`	array	Array of CSS selectors to hide (`display: none`) before capturing. Useful for removing popups, banners, or ads. Max 20 selectors.

Example: Capture a specific element

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&selector=.hero-section" \
  -o hero.png

Example: Click before capture

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "click_selector": "#accept-cookies"
  }'

Example: Hide elements

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "hide_selectors": [".cookie-banner", "#newsletter-popup", ".ads-container"]
  }'

Example: Scroll to a section

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "scroll_to": "#pricing-section"
  }'

Blocking & Filtering

Clean up screenshots by blocking cookie banners, ads, and chat widgets. These elements often clutter screenshots and aren't relevant to the content you want to capture.

Parameter	Type	Default	Description
`block_cookies`	boolean	`true`	Block cookie consent banners. Blocks consent scripts (OneTrust, CookieBot, etc.), hides banner elements, and attempts to click "Accept" buttons. Enabled by default.
`block_ads`	boolean	`false`	Block ads and trackers before capturing.
`block_chats`	boolean	`false`	Block chat widgets (Intercom, Crisp, Tawk, Drift, etc.) before capturing.

Example: Clean screenshot without distractions

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&block_ads=true&block_chats=true" \
  -o clean.png

Custom Injection

Inject custom CSS or JavaScript into the page before the screenshot is taken. You can also set custom HTTP headers and cookies to access authenticated or localized content.

Parameter	Type	Description
`css`	string	Custom CSS injected into the page. Use it to change fonts, hide elements, or adjust layout. Max 10,000 characters.
`js`	string	Custom JavaScript executed on the page. Use it to modify the DOM, pause videos, fill forms, or trigger UI changes. Max 10,000 characters.
`headers`	object	Custom HTTP headers sent with the page request. Max 20 headers, each value max 2,048 characters. Example: `{"X-Custom": "value"}`
`cookies`	array	Cookies set before loading the page. Array of objects with `name`, `value`, and optional `domain`. Max 20 cookies.

Example: Inject custom CSS

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "css": "body { font-family: Arial, sans-serif; } .sidebar { display: none; } .main-content { width: 100%; }"
  }'

Example: Execute JavaScript

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "js": "document.querySelectorAll(\"video\").forEach(v => v.pause()); document.querySelector(\"#banner\")?.remove();"
  }'

Example: Custom headers and cookies

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/dashboard",
    "headers": {
      "X-Custom-Auth": "token123",
      "Accept-Language": "de-DE"
    },
    "cookies": [
      {"name": "session_id", "value": "abc123", "domain": "example.com"},
      {"name": "theme", "value": "dark"}
    ]
  }'

Browser Emulation

Control how the browser behaves when loading the page. You can emulate dark mode, set a custom User-Agent, change the timezone, fake the geolocation, or route requests through a proxy.

Parameter	Type	Default	Description
`dark_mode`	boolean	`false`	Emulate `prefers-color-scheme: dark`. Websites that support CSS dark mode will render in their dark theme.
`reduced_motion`	boolean	`false`	Emulate `prefers-reduced-motion: reduce`. Disables CSS animations and transitions for cleaner captures.
`user_agent`	string	—	Custom User-Agent string. Overrides the device preset User-Agent. Max 500 characters.
`stealth`	boolean	`false`	Enable stealth mode. Hides browser automation signals (WebDriver flag, headless Chrome indicators, plugin counts, WebGL vendor) to bypass bot detection.
`timezone`	string	—	IANA timezone for the browser (e.g. `America/New_York`, `Europe/Berlin`, `Asia/Tokyo`). Affects `Date` and `Intl` APIs on the page.
`geolocation`	object	—	Emulate browser geolocation. Object with `latitude` (-90 to 90), `longitude` (-180 to 180), and optional `accuracy` in meters. Business plan only.
`proxy`	string	—	HTTP/SOCKS proxy URL (e.g. `http://user:pass@proxy:8080`). A dedicated browser is launched per proxy request. Business plan only. Max 2,048 characters.

Example: Dark mode

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "full_page": true,
    "dark_mode": true,
    "format": "webp"
  }'

Example: Stealth mode

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "stealth": true
  }'

Example: Custom timezone

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/dashboard",
    "timezone": "Asia/Tokyo"
  }'

Example: Geolocation

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://maps.google.com",
    "geolocation": {
      "latitude": 48.8566,
      "longitude": 2.3522,
      "accuracy": 100
    }
  }'

Example: Proxy

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "proxy": "http://user:[email protected]:8080"
  }'

PDF Options

When format is set to pdf, you can control the page layout with these additional parameters. They only apply to PDF output.

Parameter	Type	Default	Description
`pdf_landscape`	boolean	`false`	Generate PDF in landscape orientation.
`pdf_page_format`	string	`A4`	Page size: `A3`, `A4`, `A5`, `Letter`, `Legal`, or `Tabloid`.
`pdf_margin_top`	string	`10mm`	Top margin. Accepts CSS units: `10mm`, `1in`, `0`.
`pdf_margin_right`	string	`10mm`	Right margin.
`pdf_margin_bottom`	string	`10mm`	Bottom margin.
`pdf_margin_left`	string	`10mm`	Left margin.

Example: Landscape PDF with custom margins

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/report",
    "format": "pdf",
    "pdf_landscape": true,
    "pdf_page_format": "A3",
    "pdf_margin_top": "20mm",
    "pdf_margin_bottom": "20mm",
    "pdf_margin_left": "15mm",
    "pdf_margin_right": "15mm"
  }'

Advanced

Additional parameters for specific use cases.

Parameter	Type	Default	Description
`omit_background`	boolean	`false`	Capture with transparent background. Only works with PNG and WebP formats. Useful for capturing logos or UI components without a page background.
`extract_metadata`	boolean	`false`	Extract page metadata (title, description, Open Graph tags, Twitter Card, favicon URL) and include it in the screenshot response.
`cache_ttl`	integer	0	Cache duration in seconds (0–86400). If a matching screenshot exists within this period, it is returned without re-rendering. See Caching for details.
`webhook_url`	string	—	HTTPS URL to receive a POST notification when the screenshot is ready. See Webhooks.
`response_type`	string	varies	Controls the response format. `image` waits and returns the binary file directly. `json` returns a `202 Accepted` response with the screenshot object. `GET /capture` defaults to `image`; `POST /screenshots` defaults to `json`.

Example: Transparent background

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&selector=.logo&omit_background=true&format=png" \
  -o logo.png

Example: Extract metadata

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "extract_metadata": true
  }'

Example: Synchronous response from POST

curl -X POST https://api.screenshotrun.com/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "response_type": "image"
  }' \
  -o screenshot.png

Tip

When response_type is image, the API waits for the screenshot to complete and returns the binary file directly. No polling needed. The GET /v1/screenshots/capture endpoint uses this mode by default.