Skip to content
← Back to API index
GET /screenshot/create

Request a screenshot

Options

Options are grouped for easier scanning, similar to parameter-focused docs.

Essential

browser

query enum(chrome, firefox, brave) Optional

Example: chrome

Browser to use for screenshot (chrome, firefox, or brave)

country

query string Optional

Example: us

ISO 3166-1 alpha-2 country code for IP geolocation. Defaults to "us" when omitted.

Two-letter country code for routing the browser through a target country. Use this when validating localization, legal notices, pricing, and geo-specific rendering.

delay

query integer Optional

Example: 5

Seconds to wait after page load for JavaScript execution

hide_ads

query boolean Optional

Example: false

Block ads using network filtering (disabled for Brave)

Enable ad filtering for cleaner captures and visual diffs. On some browser targets, behavior may vary depending on native filtering support.

hide_popups

query boolean Optional

Example: false

Hide popups and overlays

Attempt to hide cookie banners and popup overlays before capture so outputs focus on page content.

screen_height

query integer Optional

Example: 1280

Browser viewport height in pixels

screen_width

query integer Optional

Example: 1024

Browser viewport width in pixels

size

query enum(screen, page) Optional

Example: screen

Screenshot size mode: viewport ('screen') or full page ('page')

url

query string Required

URL of the page to screenshot.

Request

cookie

query string Optional

Cookies as semicolon-separated key=value pairs

header

query string[] Optional

Custom HTTP headers. Each item should be a JSON object string. Can specify multiple header sets.

post_data

query string Optional

POST data for form submission (URL-encoded)

referer

query string Optional

Custom HTTP Referer header

user_agent

query string Optional

Custom User-Agent header to use for HTTP requests

Page

max_wait

query integer Optional

Example: 0

Maximum seconds to wait for page load (0 = disabled)

script

query string[] Optional

URL(s) of JavaScript file(s) to execute after page load. Can specify multiple scripts that will be executed in order.

script_inline

query string Optional

Inline JavaScript code to execute after page load

tracker

query object[] Optional

Alternative trackers array notation (tracker[0][id], tracker[0][name], etc.). Cannot be used with trackers.

trackers

query object[] Optional

Array of trackers to capture metrics during screenshot execution

Browser

dark

query boolean Optional

Example: false

Enable dark mode rendering

strict_ssl

query boolean Optional

Example: false

Enforce strict SSL certificate validation

Automation

step

query object[] Optional

Alternative steps array notation (step[0][command], step[0][value], etc.). Cannot be used with steps.

steps

query object[] Optional

Array of automation commands to execute before/after screenshot

JSON-encoded automation steps executed before capture. Use steps to click, type, wait, scroll, and stabilize dynamic UIs before image/PDF/video output is generated.

Screenshot

cache

query integer Optional

Example: 86400

Cache duration in seconds. 0 = always fresh, 86400 = 24 hours

shot_interval

query integer Optional

Example: 5

Seconds between sequential shots

shots

query integer Optional

Example: 1

Number of sequential screenshots

tag

query string[] Optional

Tags for organizing screenshots. Can specify multiple tags as tag=one&tag=two or comma-separated as tag=one,two

target

query string Optional

CSS selector. If provided, take a screenshot of the element. If not found within 30 seconds or max_wait, fall back to page/window screenshot.

CSS selector of the element to capture. If provided, capture is scoped to the matched element instead of the full viewport/page.

PDF Options

pdf

query boolean Optional

Example: false

Save rendered PDF

Set to true to generate a PDF artifact in addition to the screenshot. Retrieve the output later from the PDF endpoint.

pdf_background

query boolean Optional

Example: false

Include background graphics in PDF

pdf_format

query enum(a4, letter, legal) Optional

Example: letter

PDF paper format

pdf_landscape

query boolean Optional

Example: false

Render PDF in landscape mode

pdf_margin

query string Optional

Example: 20px

Default PDF margin applied to all sides — any CSS unit: px, mm, in, cm. Overridden per-side by pdf_margin_top/right/bottom/left.

pdf_margin_bottom

query string Optional

Example: 20px

Bottom margin — any CSS unit.

pdf_margin_left

query string Optional

Example: 20px

Left margin — any CSS unit.

pdf_margin_right

query string Optional

Example: 20px

Right margin — any CSS unit.

pdf_margin_top

query string Optional

Example: 20px

Top margin — any CSS unit: px, mm, in, cm.

pdf_one_page

query boolean Optional

Example: false

Fit rendered page on a single PDF page

Video Options

video

query boolean Optional

Example: false

Save a screencast video of the page loading

Set to true to generate a video recording of the page flow. Combine with `video_format`, `video_quality`, and `video_speed` for control over output.

video_colors

query integer Optional

Number of palette colors for GIF output (2-256). Fewer colors produce smaller files with some quality loss. Has no effect on WebM/MP4.

Number of palette colors used in GIF output (2–256). Reducing the palette shrinks file size with some quality trade-off. Has no effect on WebM or MP4 output.

video_duration

query integer Optional

Example: 15

Screencast recording duration in seconds (0 = no minimum recording time)

video_format

query enum(webm, mp4, gif) Optional

Example: webm

Screencast output format

video_fps

query integer Optional

Screencast frame rate (frames per second). Defaults to 20 for GIF, 30 for WebM/MP4. Lower values produce smaller GIF files.

Frame rate for the video recording. Defaults to 20 fps for GIF and 30 fps for WebM/MP4. Lower values produce smaller GIF files at the cost of smoothness.

video_quality

query integer Optional

Example: 30

Screencast quality (0-63, lower is better quality)

video_scale

query number Optional

Scale factor applied to the output video dimensions (0.1-1.0). For example, 0.5 halves both width and height, reducing file size by ~75%.

Scale factor applied to the output video dimensions (0.1–1.0). A value of 0.5 halves both width and height, reducing file size by roughly 75%.

video_speed

query number Optional

Example: 1

Screencast playback speed multiplier

App

apps

query any Optional

Apps to run after the screenshot is finished. You can pass a list of app IDs, for example `apps=google-drive&apps=dropbox`, or a deep object that maps each app ID to an optional path or filename template override, for example `apps[google-drive]=` or `apps[google-drive]={yyyy}/{mm}/{dd}/{domain}.png`.

Output & Format

html

query boolean Optional

Example: false

Save rendered HTML

Geolocation

geo_enable

query boolean Optional

Example: false

Enable geolocation emulation in the browser for this request

geo_latitude

query number Optional

Override latitude for geolocation (decimal degrees)

geo_longitude

query number Optional

Override longitude for geolocation (decimal degrees)

language

query string Optional

Override language/locale for the screenshot job (e.g., en-US, fr-FR)

timezone

query string Optional

Override timezone for geolocation (e.g., America/New_York)

Device

device_landscape

query boolean Optional

Use landscape orientation for device emulation (used with screen_width/screen_height when device_name is not set)

device_mobile

query boolean Optional

Enable mobile emulation (used with screen_width/screen_height when device_name is not set)

device_name

query string Optional

Device name to emulate (e.g., iphone_15_pro or iphone_15_pro_landscape). If provided and found, other device_* parameters are ignored.

Named device profile for viewport and input emulation. Prefer this when reproducing mobile/tablet rendering for specific real-world devices.

device_scale

query number Optional

Device scale factor (used with screen_width/screen_height when device_name is not set)

device_touch

query boolean Optional

Enable touch input for device emulation (used with screen_width/screen_height when device_name is not set)

Responses

200

Screenshot request accepted

▾ 
{
  "success": true,
  "data": {
    "id": 12345678,
    "status": "processing",
    "url": "https://example.com",
    "final_url": "https://example.com",
    "response_code": null,
    "cost": 1,
    "tag": [],
    "created_at": "2026-02-06T05:34:02.730Z",
    "finished_at": "",
    "country": "us",
    "region": "America",
    "language": "en-US",
    "timezone": "America/New_York",
    "geo_enable": false,
    "geo_latitude": 40.7128,
    "geo_longitude": -74.006,
    "size": "screen",
    "cache": 86400,
    "delay": 5,
    "screen_width": 1024,
    "screen_height": 1280,
    "priority": 2,
    "referer": "",
    "post_data": "",
    "cookie": "",
    "script": "",
    "html": false,
    "pdf": false,
    "pdf_background": false,
    "pdf_one_page": false,
    "pdf_landscape": false,
    "pdf_format": "letter",
    "pdf_margin": "0px",
    "pdf_margin_top": "0px",
    "pdf_margin_bottom": "0px",
    "pdf_margin_left": "0px",
    "pdf_margin_right": "0px",
    "video": false,
    "video_format": "webm",
    "video_quality": 30,
    "video_speed": 1,
    "video_duration": 15,
    "video_fps": null,
    "video_colors": null,
    "video_scale": null,
    "max_wait": 0,
    "header": "",
    "hide_popups": false,
    "hide_ads": false,
    "dark": false,
    "shots": 1,
    "shot_interval": 5,
    "strict_ssl": false,
    "target": "",
    "device_name": "",
    "device_scale": 3,
    "device_touch": true,
    "device_landscape": false
  }
}
400

Invalid request parameters

▾ 
{
  "error": "Request validation failed",
  "code": "VALIDATION_ERROR",
  "fields": {
    "url": [
      "URL is required"
    ],
    "country": [
      "Country code must be ISO 3166-1 alpha-2"
    ]
  }
}
401

Invalid or missing API key

▾ 
{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "details": {
    "request_id": "req_123456"
  }
}
403

Insufficient balance or account limitations

▾ 
{
  "error": "Insufficient credit balance",
  "status": "error",
  "code": "INSUFFICIENT_BALANCE"
}
429

Rate limit exceeded

▾ 
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 60
}
500

Server error

▾ 
{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "details": {
    "request_id": "req_123456"
  }
}
503

Service temporarily unavailable

▾ 
{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "details": {
    "request_id": "req_123456"
  }
}