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

All Parameters by Category

Each category has a dedicated page with detailed explanations, examples, and tips.

Category	Key Parameters	Description
Viewport & Full Page	`width`, `height`, `device`, `retina`, `full_page`	Control browser window size, device presets, retina resolution, and full-page captures.
File Type & Quality	`format`, `quality`, `resize_width`, `resize_height`, `omit_background`	Choose image format, compression quality, resize output, and transparent backgrounds.
Timing & Delay	`delay`, `timeout`, `wait_for_selector`	Control when the screenshot is taken. Handle SPAs, lazy-loaded images, and animations.
Element Screenshot	`selector`, `click_selector`, `scroll_to`, `hide_selectors`	Capture specific elements, click before capture, scroll to sections, and hide distractions.
CSS & JS Injection	`css`, `js`, `headers`, `cookies`	Inject custom CSS/JavaScript, set HTTP headers and cookies for authenticated pages.
Blocking & Filtering	`block_cookies`, `block_ads`, `block_chats`	Block cookie banners, ads, and chat widgets for clean screenshots.
Browser Emulation	`dark_mode`, `reduced_motion`, `stealth`, `user_agent`, `timezone`, `geolocation`, `proxy`	Emulate dark mode, stealth browsing, timezones, geolocation, and proxy routing.
PDF Rendering	`pdf_landscape`, `pdf_page_format`, `pdf_margin_*`	Generate PDF documents with custom page size, orientation, and margins.

Scrolling Video

Capture a scrolling video of a page instead of a static screenshot. The API scrolls the page from top to bottom and records the viewport as a WebM video.

Parameter	Type	Default	Description
`scroll_video`	boolean	`false`	Enable scrolling video mode. When `true`, the API returns a WebM video file instead of a static image.
`scroll_duration`	integer	5	Total scroll duration in seconds (1–30). Longer durations produce smoother videos for long pages.
`scroll_speed`	string	`medium`	Scroll speed preset: `slow`, `medium`, or `fast`.

Example: Capture a scrolling video

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&scroll_video=true&scroll_duration=8&scroll_speed=slow" \
  -o scroll.webm

Note

Scrolling videos take longer to process than static screenshots because the browser must record the entire scroll. Set your HTTP client timeout accordingly (at least scroll_duration + 30 seconds). The output format is always WebM regardless of the format parameter.

Advanced

Additional parameters for specific use cases.

Parameter	Type	Default	Description
`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: 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.