Docs

Screenshot Options

This document lists all available screenshot options you can use when requesting a screenshot render.

The SDKs and the CLI take the same options, with names in their own style, such as fullPage in Node.js.

Target & output

url

string · required

The URL of the page you want to take a screenshot of. The page must be publicly reachable; localhost and private network addresses are not supported.

POST request body example:

{
  "url": "https://example.com/"
}

format

string · optional

The output format of the screenshot.

  • Default: png
  • Allowed: jpg, jpeg (alias for jpg), png, gif, webp, pdf, tiff

POST request body example:

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

response_type

string · optional

Choose whether you want the API to return a raw binary or a JSON with the URL of the screenshot.

  • Default: binary

  • Allowed:

    • binary: Returns the raw binary with an appropriate Content-Type. We will also return the screenshot URL via the Screenshot-Scout-Screenshot-URL response header. If cache=true, we will also return the screenshot expiration date and the cache status (HIT, MISS) via Screenshot-Scout-Screenshot-URL-Expires-At and Screenshot-Scout-Cache-Status response headers respectively.
    • json: Returns a JSON object with the screenshot_url property containing the URL of the screenshot. If cache=true, the JSON object will also contain the screenshot expiration date and the cache status (hit, miss) in the screenshot_url_expires_at and cache_status properties respectively.

POST request body example:

{
  "url": "https://example.com/",
  "response_type": "json"
}

JSON response example:

{
  "screenshot_url": "https://cdn.screenshotscout.com/cdafae824c3a09d30a9660cd6473025b7ec7d9d8828722490502511c97076163.png"
}

Screenshot URL lifetime:

In both response types, the screenshot URL is temporary. By default, we keep the screenshot for 4 hours after rendering and then delete it, after which the URL stops working. Don't save the URL for later use or embed it in pages that need to keep working.

To keep a screenshot, either save the returned image yourself (or download it from the screenshot URL before it expires), or set storage_mode to external so that we upload it to your own S3-compatible bucket, where we never delete it. External storage is the recommended option for long-term or permanent storage.

If you only need the URL to stay available for longer than 4 hours, you can use caching instead: a cached screenshot stays available for the cache_ttl you set, up to 30 days. Caching is designed for reusing identical screenshots, not for storage.

Network & location

country

string · optional

Navigate to the specified URL via a proxy in the selected country. This is useful when the URL contains country-dependent content and you would like to capture the URL as if the user would access the URL from that country. This screenshot option is only available on paid plans. If proxy is provided, it takes precedence over country.

  • Default: not set. We will navigate to the specified URL via our servers in the US.
  • Allowed: any two-letter uppercase ISO code, e.g. US, CA, DE

POST request body example:

{
  "url": "https://example.com/",
  "country": "CA"
}

proxy

string · optional

Navigate to the specified URL via an HTTP/HTTPS/SOCKS5 proxy you provide. When provided, takes precedence over country (if provided).

  • Default: not set. We will navigate to the specified URL directly via our servers in the US.
  • Allowed: a string in the following format: http://user:pass@host:port. HTTPS proxies must support HTTP/1.1.

POST request body example:

{
  "url": "https://example.com/",
  "proxy": "http://user:pass@proxy.example.com:3128"
}

geolocation_latitude

number · optional

Set the emulated latitude for the browser's Geolocation API. Must be used in combination with geolocation_longitude. If geolocation_longitude is not provided, geolocation_latitude is ignored.

  • Default: not set
  • Allowed values: a number between -90 and +90 (inclusive)

POST request body example:

{
  "url": "https://example.com/",
  "geolocation_latitude": 40.730610,
  "geolocation_longitude": -73.935242
}

geolocation_longitude

number · optional

Set the emulated longitude for the browser's Geolocation API. Must be used in combination with geolocation_latitude. If geolocation_latitude is not provided, geolocation_longitude is ignored.

  • Default: not set
  • Allowed values: a number between -180 and +180 (inclusive)

POST request body example:

{
  "url": "https://example.com/",
  "geolocation_latitude": 40.730610,
  "geolocation_longitude": -73.935242
}

geolocation_accuracy

number · optional

Set the emulated accuracy of the geolocation. Only used in combination with geolocation_latitude and geolocation_longitude. If geolocation_latitude or geolocation_longitude is not provided, geolocation_accuracy is ignored.

  • Default: not set
  • Allowed values: a number >= 0

POST request body example:

{
  "url": "https://example.com/",
  "geolocation_latitude": 40.730610,
  "geolocation_longitude": -73.935242,
  "geolocation_accuracy": 50
}

Cookies & headers

cookies

array of strings · optional

Set HTTP cookies in the browser before navigation in the Set-Cookie-style format. To set several cookies, pass one value per cookie.

  • Default: not set
  • Allowed values: each value is a single Set-Cookie-style line

POST request body example:

{
  "url": "https://example.com/",
  "cookies": ["sessionid=abc123; Path=/; Secure; HttpOnly", "theme=dark; Path=/"]
}

headers

array of strings · optional

Add an extra HTTP header to the outgoing request. To add several headers, pass one value per header. If you want to overwrite any of the default request headers, you can do so as well.

  • Default: not set
  • Allowed values: each value must be in the Name:Value form

POST request body example:

{
  "url": "https://example.com/",
  "headers": ["Accept-Language:en", "X-Experiment:variantA"]
}

timeout

integer (seconds) · optional

Set a hard request-wide limit in seconds on how long to wait before the screenshot request is considered failed. The default value is 120 seconds, which is sufficient for the majority of screenshot requests. If you constantly experience timeouts, consider increasing the timeout. If, however, you want to decrease the timeout below the default value, please consider that it could significantly increase the number of failed screenshot requests.

Note that timeout is different from navigation_timeout, which is responsible for navigation timeout only, not the request-wide timeout.

  • Default: 120
  • Allowed values: 1–240 (inclusive)

POST request body example:

{
  "url": "https://example.com/",
  "timeout": 180
}

wait_until

string · optional

Control when the navigation (the page load phase) is considered complete, and we can proceed to taking the screenshot.

There are a few reasons why you might want to use this screenshot option. If you care more about speed rather than the quality of the screenshots (whether all elements are fully loaded or not), choose domcontentloaded. If, however, you care more about quality than speed, choose networkidle2 (the default). While, technically, choosing networkidle0 may increase the quality of the screenshots even further, we advise against using it as it is the longest option and might result in a significant increase in timeouts.

  • Default: networkidle2

  • Allowed values:

    • domcontentloaded: Wait for the DOMContentLoaded event (HTML fully parsed).
    • load: Wait for the load event to fire.
    • networkidle2: Wait until there are no more than 2 network connections.
    • networkidle0: Wait until there are no network connections at all (meaning the page is fully loaded).

POST request body example:

{
  "url": "https://example.com/",
  "wait_until": "domcontentloaded"
}

integer (seconds) · optional

Set a per-navigation (the page load phase) timeout, before proceeding to taking the screenshot. The maximum and default value is 90 seconds. Because the majority of pages fully load much faster than that, if you would like for the navigation and the entire screenshot request to fail faster, you could consider decreasing this timeout. Change this option with caution as it could potentially significantly increase the number of failed requests.

Note that if navigation_timeout is reached, the screenshot request will fail, even though the request-wide timeout has not been reached yet.

  • Default: 90
  • Allowed values: 5–90 (inclusive)

POST request body example:

{
  "url": "https://example.com/",
  "navigation_timeout": 60
}

delay

integer (seconds) · optional

A delay, in seconds, that happens after navigation has finished, and right before taking the screenshot. Use this if you constantly experience some parts of the page not fully loaded when looking at the screenshots, and you already use wait_until=networkidle2 and do not want to set it to networkidle0 (which we recommend you never do).

  • Default: 0 (no delay)
  • Allowed values: 0–30 (inclusive)

POST request body example:

{
  "url": "https://example.com/",
  "delay": 10
}

Viewport & device emulation

device

string · optional

A preset used to emulate real devices, like Apple iPhone, Samsung Galaxy, Google Pixel, etc. When used, the screenshots will look exactly the same the URL would look on a real device.

If device is set, and no explicit device_viewport_width, device_viewport_height, device_scale_factor, device_is_mobile, device_has_touch, device_user_agent have been provided, the values for these options will be derived from the preset. If any of the options mentioned is provided, the provided value will overwrite the one that comes with the preset for that option.

  • Default: not set
  • Allowed values: must be one of the supported device names.

POST request body example:

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

device_viewport_width

integer · optional

Set the viewport width used when taking a screenshot, in pixels. By default, the screenshot has the same width as the viewport. To change the screenshot's width without changing the viewport, use image_width.

  • Default: 1920 if device is not provided. If device is provided, the default device_viewport_width is derived from the provided device preset.
  • Allowed values: any integer value, e.g. 1920, 1440, 1280

POST request body example:

{
  "url": "https://example.com/",
  "device_viewport_width": 1280
}

device_viewport_height

integer · optional

Set the viewport height used when taking a screenshot, in pixels. By default, the screenshot has the same height as the viewport. To change the screenshot's height without changing the viewport, use image_height.

  • Default: 1080 if device is not provided. If device is provided, the default device_viewport_height is derived from the provided device preset.
  • Allowed values: any integer value, e.g. 1080, 900, 720

POST request body example:

{
  "url": "https://example.com/",
  "device_viewport_height": 720
}

device_scale_factor

number · optional

Set the device scale factor (DPR) to emulate retina-like displays. Set it to 1 (default) to get the regular pixel density, or 2 or higher to get retina/high-resolution (sharper text and images, bigger file). If both device_scale_factor and device are provided, the provided device_scale_factor overrides the default that comes with the device preset.

  • Default: 1
  • Allowed values: a number > 0

POST request body example:

{
  "url": "https://example.com/",
  "device_scale_factor": 2
}

device_is_mobile

boolean · optional

Hint to the browser that the device used is a mobile device. If you would like to emulate a mobile device when taking a screenshot, but don't want to use any of the device presets, you should always set device_is_mobile to true. If both device_is_mobile and device are provided, the provided device_is_mobile overrides the default that comes with the device preset.

  • Default: not set
  • Allowed values: true, false

POST request body example:

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

device_has_touch

boolean · optional

Hint to the browser that the device has touch support. Whenever you set device_is_mobile to true, it's also advised to set device_has_touch to true as well. If both device_has_touch and device are provided, the provided device_has_touch overrides the default that comes with the device preset.

  • Default: not set
  • Allowed values: true, false

POST request body example:

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

device_user_agent

string · optional

Override the browser user agent string sent with the request. Use with caution as setting this manually may trigger CAPTCHAs or other protective measures on the site's side when taking the screenshot. If both device_user_agent and device are provided, the provided device_user_agent overrides the default that comes with the device preset.

  • Default: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36 (subject to change and is not guaranteed)
  • Allowed values: any non-empty string

POST request body example:

{
  "url": "https://example.com/",
  "device_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"
}

Page behavior & preferences

timezone

string · optional

Emulate a specific timezone inside the browser. Use this when taking screenshots of pages whose content depends on your local timezone, like calendars, local time services, etc.

  • Default: not set
  • Allowed values: any IANA timezone ID, e.g. America/New_York, Europe/Berlin

POST request body example:

{
  "url": "https://example.com/",
  "timezone": "America/New_York"
}

media_type

string · optional

Set the page's emulated media type (screen vs print) that can change how the page looks. Applies to all formats, not just pdf.

  • Default:

    • For pdf: print
    • For other formats: screen
  • Allowed values:

    • screen: emulate normal screen media, which is the regular option for screenshots
    • print: emulate print media; when used, it applies @media print CSS, often simplifying the layout.

POST request body example:

{
  "url": "https://example.com/",
  "media_type": "print"
}

color_scheme

string · optional

Emulate the user's preferred color scheme (prefers-color-scheme) to trigger light/dark theme variants. Only works when these variants are supported by the target website.

  • Default: auto

  • Allowed values:

    • auto: no explicit emulation; use whatever is the default for the website
    • light: force light color scheme
    • dark: force dark color scheme

POST request body example:

{
  "url": "https://example.com/",
  "color_scheme": "dark"
}

reduced_motion

boolean · optional

Emulate the prefers-reduced-motion preference. Use this to reduce or disable animations on the page to avoid capturing screenshots with animations or videos mid-transition. Consider using this option alongside delay so the target page can settle in reduced-motion state.

  • Default: false
  • Allowed values: true, false

POST request body example:

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

Full-page & scrolling behavior

full_page

boolean · optional

Set full_page to true to capture the entire scrollable page, not just the visible viewport. Ignored for format=pdf: a PDF always contains the whole page.

  • Default: false
  • Allowed values: true, false

POST request body example:

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

full_page_pre_scroll

boolean · optional

Set full_page_pre_scroll to true (default) to scroll the entire page before capturing the screenshot. This triggers all lazy-loaded assets on the page, including images, to make sure they're visible when capturing the screenshot. Note that scrolling the page may take a long time. If you don't care about all lazy-loaded assets being present in the screenshot, consider setting full_page_pre_scroll to false to speed up screenshot rendering.

  • Default: true
  • Allowed values: true, false

POST request body example:

{
  "url": "https://example.com/",
  "full_page": true,
  "full_page_pre_scroll": false
}

full_page_pre_scroll_step

integer (pixels) · optional

When full_page_pre_scroll=true, we scroll the page down to trigger all lazy-loaded assets before capturing the screenshot. Scrolling is done in steps, with a small delay after each step. You can use full_page_pre_scroll_step to set the vertical scroll step size in pixels, thus controlling how effectively the lazy-loaded assets are triggered.

The default value is equal to 0.8 of device_viewport_height. If you constantly see that some lazy-loaded images are still not loaded in the screenshots, consider explicitly setting full_page_pre_scroll_step to a number of pixels less than 0.8 of device_viewport_height. For example, if device_viewport_height is 1080 pixels (default), the default full_page_pre_scroll_step is 864 (1080 x 0.8). You may want to change it to 600 and see if the lazy-loaded assets are now present in the screenshot.

Note that the smaller the step, the longer it takes to scroll the page and, in some cases, it may cause additional timeouts.

  • Default: device_viewport_height * 0.8 (clamped to 240 minimum, 2000 maximum)
  • Allowed values: 240–2000 (inclusive)

POST request body example:

{
  "url": "https://example.com/",
  "full_page": true,
  "full_page_pre_scroll_step": 600
}

full_page_pre_scroll_step_delay

integer (milliseconds) · optional

Set the delay between steps when full_page=true and full_page_pre_scroll=true, giving time for lazy-loaded assets to load during scrolling. The longer the delay, the more chances that the lazy-loaded assets will load during each scroll step. Note that longer delays between steps may cause additional timeouts.

  • Default: 200
  • Allowed values: 50–1000 (inclusive)

POST request body example:

{
  "url": "https://example.com/",
  "full_page": true,
  "full_page_pre_scroll_step_delay": 400
}

full_page_max_height

integer (pixels) · optional

Set the maximum height of the page to capture when full_page=true. Consider using this option when capturing very long pages (approximately 100,000 pixels), or pages with infinite scroll.

  • Default: 0 (the maximum height is not limited)
  • Allowed values: an integer >= 0

POST request body example:

{
  "url": "https://example.com/",
  "full_page": true,
  "full_page_max_height": 50000
}

Blocking

boolean · optional

Attempt to block/hide cookie popups before capturing a screenshot. Note that if you are fine with ads being hidden on the page, consider setting block_ads to true as well. This allows us to use a more aggressive algorithm when blocking/hiding cookie popups, resulting in more of them being blocked/hidden.

  • Default: false
  • Allowed values: true, false

POST request body example:

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

block_ads

boolean · optional

Attempt to block/hide ads on the page.

  • Default: false
  • Allowed values: true, false

POST request body example:

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

block_chat_widgets

boolean · optional

Attempt to block/hide chat widgets and similar overlays.

  • Default: false
  • Allowed values: true, false

POST request body example:

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

DOM interactions & injections

hide_selectors

array of strings · optional

Hide all elements that match the specified CSS selector by applying display: none to them. If you need to hide elements matching several CSS selectors, pass one value per selector.

  • Default: not set
  • Allowed values: any non-empty CSS selector string

POST request body example:

{
  "url": "https://example.com/",
  "hide_selectors": [".cookie-banner", "#ad-overlay"]
}

click_selectors

array of strings · optional

Click the first element matching the specified CSS selector. If you need to click elements matching several CSS selectors, pass one value per selector. The elements are clicked in the order you list the selectors.

  • Default: not set
  • Allowed values: any non-empty CSS selector string

POST request body example:

{
  "url": "https://example.com/",
  "click_selectors": ["#open-modal", ".accept-btn"]
}

click_all_selectors

array of strings · optional

Click all elements matching the specified CSS selector. If you need to click elements matching several CSS selectors, pass one value per selector. The elements are clicked in the order you list the selectors.

  • Default: not set
  • Allowed values: any non-empty CSS selector string

POST request body example:

{
  "url": "https://example.com/",
  "click_all_selectors": [".accordion-toggle"]
}

inject_css

array of strings · optional

Inject custom CSS into the page before capturing a screenshot. You can pass several values. Use it whenever you need to make changes to the layout before capturing the screenshot.

  • Default: not set
  • Allowed values: any non-empty string

POST request body example:

{
  "url": "https://example.com/",
  "inject_css": ["body {background:red !important;}"]
}

inject_js

array of strings · optional

Inject custom JavaScript into the page before capturing a screenshot. You can pass several values. Use this to perform actions or dynamic DOM changes before the screenshot is taken that can't be done with CSS. Note that if the target page has a strict Content Security Policy that blocks inline scripts, you may need to set bypass_csp to true.

  • Default: not set
  • Allowed values: any non-empty string

POST request body example:

{
  "url": "https://example.com/",
  "inject_js": ["document.querySelector('.banner')?.remove();"]
}

bypass_csp

boolean · optional

Bypass (disable) the page's Content Security Policy (CSP). If your inject_js or inject_css doesn't take effect and/or the screenshot shows a "blocked by CSP" / "refused to execute" message, try setting bypass_csp=true.

  • Default: false
  • Allowed values: true, false

POST request body example:

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

Framing & selection

selector

string · optional

Capture a screenshot of a DOM element matching the specified CSS selector, instead of the whole viewport or full page. Ignored for format=pdf.

  • Default: not set
  • Allowed values: any non-empty CSS selector string

POST request body example:

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

clip_x

integer (pixels) · optional

Set the X coordinate (left) of a rectangular clip region in pixels, measured from the top-left of the page. To capture a rectangular clip region, you must set all 4 required options: clip_x, clip_y, clip_width, clip_height. If any of the 4 are missing or invalid, all clip options are ignored. Ignored for format=pdf.

  • Default: not set
  • Allowed values: integer >= 0

POST request body example:

{
  "url": "https://example.com/",
  "clip_x": 0,
  "clip_y": 100,
  "clip_width": 600,
  "clip_height": 400
}

clip_y

integer (pixels) · optional

Set the Y coordinate (top) of a rectangular clip region in pixels, measured from the top-left of the page. To capture a rectangular clip region, you must set all 4 required options: clip_x, clip_y, clip_width, clip_height. If any of the 4 are missing or invalid, all clip options are ignored. Ignored for format=pdf.

  • Default: not set
  • Allowed values: integer >= 0

POST request body example:

{
  "url": "https://example.com/",
  "clip_x": 0,
  "clip_y": 100,
  "clip_width": 600,
  "clip_height": 400
}

clip_width

integer (pixels) · optional

Set the width of a rectangular clip region in pixels. To capture a rectangular clip region, you must set all 4 required options: clip_x, clip_y, clip_width, clip_height. If any of the 4 are missing or invalid, all clip options are ignored. Ignored for format=pdf.

  • Default: not set
  • Allowed values: 1–8192 (inclusive)

POST request body example:

{
  "url": "https://example.com/",
  "clip_x": 0,
  "clip_y": 100,
  "clip_width": 600,
  "clip_height": 400
}

clip_height

integer (pixels) · optional

Set the height of a rectangular clip region in pixels. To capture a rectangular clip region, you must set all 4 required options: clip_x, clip_y, clip_width, clip_height. If any of the 4 are missing or invalid, all clip options are ignored. Ignored for format=pdf.

  • Default: not set
  • Allowed values: 1–8192 (inclusive)

POST request body example:

{
  "url": "https://example.com/",
  "clip_x": 0,
  "clip_y": 100,
  "clip_width": 600,
  "clip_height": 400
}

Image resizing & quality

image_width

integer (pixels) · optional

Set the output width in pixels for the final image. Ignored for format=pdf.

  • Default: not set. The image width is derived from viewport width, clip region width, selector width, etc.
  • Allowed values: 1–8192 (inclusive); image_width * image_height must be <= 64,000,000 pixels

POST request body example:

{
  "url": "https://example.com/",
  "image_width": 200
}

image_height

integer (pixels) · optional

Set the output height in pixels for the final image. Ignored for format=pdf.

  • Default: not set. The image height is derived from viewport height, clip region height, selector height, etc.
  • Allowed values: 1–8192 (inclusive); image_width * image_height must be <= 64,000,000 pixels

POST request body example:

{
  "url": "https://example.com/",
  "image_height": 100
}

image_mode

string · optional

Control how the image is resized/cropped when both image_width and image_height are specified. If only one of them is specified, the image is resized proportionally and image_mode is ignored.

  • Default: fit

  • Allowed values:

    • fit: Fit the entire source image (after capture, before resize) within the target box, preserving aspect ratio (may leave empty bands).
    • fill: Fill the target box, possibly cropping; preserves aspect ratio.
    • stretch: Stretch the image non-uniformly to fill the box; does not preserve aspect ratio.

POST request body example:

{
  "url": "https://example.com/",
  "image_width": 200,
  "image_height": 100,
  "image_mode": "fill"
}

image_anchor

string · optional

Set the anchor point used when deciding where to position the image inside the canvas (when image_mode=fit), or which side/area of the bigger image to keep when cropping (when image_mode=fill). Only applied when both image_width and image_height are specified.

  • Default: center
  • Allowed values: center, top, bottom, left, right, top_left, top_right, bottom_left, bottom_right

POST request body example:

{
  "url": "https://example.com/",
  "image_width": 200,
  "image_height": 100,
  "image_mode": "fill",
  "image_anchor": "top_left"
}

image_allow_upscale

boolean · optional

Control whether the post-capture image (before resize) is allowed to be enlarged (upscaled) up to the specified image_width and/or image_height.

  • Default: false
  • Allowed values: true, false

POST request body example:

{
  "url": "https://example.com/",
  "image_width": 2000,
  "image_allow_upscale": true
}

image_background

string (hex color) · optional

Set the background color for the empty areas of the output when both image_width and image_height are specified, image_mode is fit, and the resized screenshot does not occupy the entire canvas.

  • Default:

    • For jpg or gif: #FFFFFF
    • For other formats: transparent
  • Allowed values: hex color in the form #RRGGBB (case-insensitive)

POST request body example:

{
  "url": "https://example.com/",
  "format": "jpg",
  "image_width": 1200,
  "image_height": 1200,
  "image_background": "#FF0000"
}

image_quality

integer · optional

Set compression quality for lossy formats (jpg or webp). Ignored for other formats.

  • Default: 80
  • Allowed values: 0–100 (inclusive)

POST request body example:

{
  "url": "https://example.com/",
  "format": "webp",
  "image_quality": 100
}

PDF options

pdf_paper_format

string · optional

Set the PDF paper size when generating PDFs (format=pdf).

  • Default: letter

  • Allowed values:

    • letter
    • legal
    • tabloid
    • a3
    • a4
    • a5
    • a6

POST request body example:

{
  "url": "https://example.com/",
  "format": "pdf",
  "pdf_paper_format": "a4"
}

pdf_landscape

boolean · optional

Specify whether you want the page orientation in PDFs to be portrait or landscape format. Only used when format=pdf.

  • Default: false
  • Allowed values: true, false

POST request body example:

{
  "url": "https://example.com/",
  "format": "pdf",
  "pdf_landscape": true
}

pdf_print_background

boolean · optional

Specify whether CSS backgrounds should be included in the PDF output.

  • Default: true
  • Allowed values: true, false

POST request body example:

{
  "url": "https://example.com/",
  "format": "pdf",
  "pdf_print_background": false
}

pdf_margin

string · optional

Set a base margin applied to all sides in PDFs, unless overridden by side-specific margins (pdf_margin_top, pdf_margin_right, pdf_margin_bottom, pdf_margin_left).

  • Default: 0
  • Allowed values: non-negative CSS length in units: px, in, mm, or cm (e.g. 10px, 0.5in, 12mm)

POST request body example:

{
  "url": "https://example.com/",
  "format": "pdf",
  "pdf_margin": "0.5in"
}

pdf_margin_top

string · optional

Set the top margin in PDFs. When pdf_margin is specified, pdf_margin_top overrides the top margin set by pdf_margin.

  • Default: 0 if pdf_margin is not provided; otherwise, the default value is derived from pdf_margin
  • Allowed values: non-negative CSS length in units: px, in, mm, or cm (e.g. 10px, 0.5in, 12mm)

POST request body example:

{
  "url": "https://example.com/",
  "format": "pdf",
  "pdf_margin_top": "0.5in"
}

pdf_margin_right

string · optional

Set the right margin in PDFs. When pdf_margin is specified, pdf_margin_right overrides the right margin set by pdf_margin.

  • Default: 0 if pdf_margin is not provided; otherwise, the default value is derived from pdf_margin
  • Allowed values: non-negative CSS length in units: px, in, mm, or cm (e.g. 10px, 0.5in, 12mm)

POST request body example:

{
  "url": "https://example.com/",
  "format": "pdf",
  "pdf_margin_right": "0.5in"
}

pdf_margin_bottom

string · optional

Set the bottom margin in PDFs. When pdf_margin is specified, pdf_margin_bottom overrides the bottom margin set by pdf_margin.

  • Default: 0 if pdf_margin is not provided; otherwise, the default value is derived from pdf_margin
  • Allowed values: non-negative CSS length in units: px, in, mm, or cm (e.g. 10px, 0.5in, 12mm)

POST request body example:

{
  "url": "https://example.com/",
  "format": "pdf",
  "pdf_margin_bottom": "0.5in"
}

pdf_margin_left

string · optional

Set the left margin in PDFs. When pdf_margin is specified, pdf_margin_left overrides the left margin set by pdf_margin.

  • Default: 0 if pdf_margin is not provided; otherwise, the default value is derived from pdf_margin
  • Allowed values: non-negative CSS length in units: px, in, mm, or cm (e.g. 10px, 0.5in, 12mm)

POST request body example:

{
  "url": "https://example.com/",
  "format": "pdf",
  "pdf_margin_left": "0.5in"
}

pdf_scale

number (float) · optional

Scale the page when printing the PDF, without changing the paper size. Values below 1 make the content smaller, so the page is laid out wider and more of it fits on each page. Values above 1 make the content larger.

  • Default: 1
  • Allowed values: 0.1–2 (inclusive), e.g. 0.75, 1.5

POST request body example:

{
  "url": "https://example.com/",
  "format": "pdf",
  "pdf_scale": 0.75
}

pdf_page_ranges

string · optional

Choose which pages of the PDF to return, as comma-separated page numbers or ranges, such as 1-3,5. Pages start at 1.

  • Default: not set (all pages)
  • Allowed values: comma-separated page numbers (>= 1) or ranges start-end where start <= end, up to 256 characters (e.g. 1, 1-3, 2,4-6)

POST request body example:

{
  "url": "https://example.com/",
  "format": "pdf",
  "pdf_page_ranges": "1-3,5"
}

Caching

cache

boolean · optional

When you set cache to true, identical requests will be served from storage (if present in the storage) instead of re-rendering.

Whenever you send a request with cache=true, we will also return the screenshot URL expiration date, as well as the cache status (hit or miss). With response_type=binary (default), they're in the Screenshot-Scout-Screenshot-URL-Expires-At and Screenshot-Scout-Cache-Status (HIT, MISS) response headers. With response_type=json, they're in the screenshot_url_expires_at and cache_status (hit, miss) JSON properties.

  • Default: false
  • Allowed values: true, false

POST request body example:

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

cache_ttl

integer (seconds) · optional

Set how long cached objects are stored.

  • Default: 14400 seconds (4 hours)
  • Allowed values: 14400–2592000 seconds (4 hours–30 days) inclusive

POST request body example:

{
  "url": "https://example.com/",
  "cache": true,
  "cache_ttl": 86400
}

cache_key

string · optional

Allow multiple distinct cached versions for the same set of options, keyed by the cache_key string.

  • Default: not set
  • Allowed values: any non-empty string

POST request body example:

{
  "url": "https://example.com/",
  "cache": true,
  "cache_key": "homepage-variant-b"
}

Storage

storage_mode

string · optional

Choose between Screenshot Scout's managed storage and your own external S3-compatible storage when saving captured screenshots.

  • Default: managed

  • Allowed values:

    • managed: Store in Screenshot Scout's own managed storage.
    • external: Store in your own S3-compatible bucket. When storage_mode=external, you must configure your credentials in the panel. The endpoint, bucket, and region can either be configured in the panel, or via options storage_endpoint, storage_bucket, and storage_region respectively.

POST request body example:

{
  "url": "https://example.com/",
  "storage_mode": "external"
}

storage_endpoint

string (URL) · optional, but effectively required when storage_mode=external and no endpoint is configured in the panel

Specify the HTTPS endpoint for your external S3-compatible storage.

  • Default: the panel-configured endpoint
  • Allowed values: any non-empty string starting with https://

POST request body example:

{
  "url": "https://example.com/",
  "storage_mode": "external",
  "storage_endpoint": "https://s3.us-east-2.amazonaws.com"
}

storage_bucket

string · optional, but effectively required when storage_mode=external and no bucket is configured in the panel

Specify the S3 bucket name to write screenshots into when using external storage.

  • Default: the panel-configured bucket
  • Allowed values: any non-empty string

POST request body example:

{
  "url": "https://example.com/",
  "storage_mode": "external",
  "storage_bucket": "my-screenshots"
}

storage_region

string · optional

Specify the region for your S3-compatible storage when relevant.

  • Default: the panel-configured region
  • Allowed values: any non-empty string

POST request body example:

{
  "url": "https://example.com/",
  "storage_mode": "external",
  "storage_region": "us-east-2"
}

storage_object_key

string (without extension) · optional

Override the object key (filename without extension) used when writing to external storage. When storage_mode=external and storage_object_key is present, the final key becomes storage_object_key + "." + format.

Note that when cache=true and storage_object_key is present, we will use storage_object_key when attempting to retrieve the cached version of the screenshot. If you expect the cached version to be different for each unique set of screenshot options (which is the default behavior when storage_object_key is not present), you must make sure that storage_object_key is unique per each unique set of screenshot options (url, format, response_type, and any other options you use).

  • Default: not set. The key is derived from the screenshot options you use.
  • Allowed values: any non-empty string that must not contain a dot (.)

POST request body example:

{
  "url": "https://example.com/",
  "storage_mode": "external",
  "storage_object_key": "users/acme/homepage-latest"
}