Screenshot Options

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

If you ever plan to publicly share the entire request URL with your access_key in it, you might want to consider toggling the "Require signed requests" toggle when creating an API key. When you do so, each request will require an HMAC-SHA256 signature, which will be unique for each set of screenshot options you use. Learn more about signed requests here.

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&signature=ffc374335e0958e3284350be84b3df5c413f0af72a55507ec3bc3638848f9749

Target & output

url

string · required

The URL of the page you want to take a screenshot of.

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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.

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&response_type=json

JSON response example:

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

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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:3128

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&proxy=http://user:pass@host: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 or invalid, geolocation_latitude is ignored.

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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 or invalid, geolocation_longitude is ignored.

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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 either geolocation_latitude or geolocation_longitude are not provided or invalid, geolocation_accuracy is ignored.

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&geolocation_latitude=40.730610&geolocation_longitude=-73.935242&geolocation_accuracy=50

Cookies & headers

cookies

repeated string · optional

Set HTTP cookies in the browser before navigation in the Set-Cookie-style format. To set multiple cookies, use the cookies param multiple times.

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&cookies=sessionid=abc123; Path=/; Secure; HttpOnly&cookies=theme=dark; Path=/

headers

repeated string · optional

Add an extra HTTP header to the outgoing request. If you want to pass multiple headers, use the headers param multiple times. If you want to overwrite any of the default request headers, you can do so as well.

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&headers=Accept-Language:en&headers=X-Experiment:variantA

timeout

integer · 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)

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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).

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&wait_until=domcontentloaded

navigation_timeout

integer · 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)

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&navigation_timeout=60

delay

integer · optional

A delay 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
Allowed values: 0–30 (inclusive)

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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.

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&device=iPhone 15

device_viewport_width

integer · optional

Set the viewport width used when taking a screenshot, in pixels. If the width option is not provided, device_viewport_width will also be the width of the output screenshot.

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&device_viewport_width=1280

device_viewport_height

integer · optional

Set the viewport height used when taking a screenshot, in pixels. If the height option is not provided, device_viewport_height will also be the height of the output screenshot.

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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: 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.

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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.

Default: false
Allowed values: true, false

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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)

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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)

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&full_page=true&full_page_max_height=50000

Blocking

block_cookie_banners

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&block_chat_widgets=true

DOM interactions & injections

hide_selectors

repeated string · optional

Hide all elements that match the specified CSS selector by applying display: none to them. If you need to hide elements matching multiple CSS selectors, specify the hide_selectors param multiple times in the request URL.

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&hide_selectors=.cookie-banner&hide_selectors=#ad-overlay

click_selectors

repeated string · optional

Click the first element matching the specified CSS selector. If you need to click elements matching multiple CSS selectors, specify the click_selectors param multiple times in the request URL. The elements are clicked in the same order you specify the CSS selectors in the request string.

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&click_selectors=#open-modal&click_selectors=.accept-btn

click_all_selectors

repeated string · optional

Click all elements matching the specified CSS selector. If you need to click elements matching multiple CSS selectors, specify the click_all_selectors param multiple times in the request URL. The elements are clicked in the same order you specify the CSS selectors in the request string.

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&click_all_selectors=.accordion-toggle

inject_css

repeated string · optional

Inject custom CSS into the page before capturing a screenshot. You can provide multiple inject_css params in the request URL. Use it whenever you need to make changes to the layout before capturing the screenshot.

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&inject_css=body {background:red !important;}

inject_js

repeated string · optional

Inject custom JavaScript into the page before capturing a screenshot. You can provide multiple inject_js params in the request URL. 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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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.

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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.

Default: not set
Allowed values: integer >= 0

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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.

Default: not set
Allowed values: integer >= 0

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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.

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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.

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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 raster image / PDF raster.

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&image_width=200

image_height

integer (pixels) · optional

Set the output height in pixels for the final raster image / PDF raster.

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&image_height=100

image_mode

string · optional

Control how the image is resized/cropped when image_width and/or image_height are specified. Only applied when image_width and/or image_height is specified.

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.

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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 image_width and/or image_height is specified.

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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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 image_width and/or image_height are specified 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)

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&format=jpg&image_width=2000&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)

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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
- a4
- a3
- content: the PDF is sized to the content rather than a fixed paper size

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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)

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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)

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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)

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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)

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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)

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&format=pdf&pdf_margin_left=0.5in

pdf_scale

number (float) · optional

Scale the post-capture screenshot inside the PDF relative to the default. Use this option when the captured screenshot looks too small or large inside the PDF paper, but you don’t want to change the paper size itself.

Default: 1
Allowed values: number > 0 and <= 3 (e.g. 0.75, 1.5)

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&format=pdf&pdf_scale=1.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):

via response headers Screenshot-Scout-Screenshot-URL-Expires-At and Screenshot-Scout-Cache-Status (HIT, MISS) respectively when response_type=binary (default), or
via JSON properties screenshot_url_expires_at and cache_status (hit, miss) respectively when response_type=json
Default: false
Allowed values: true, false

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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.

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&storage_mode=external

storage_endpoint

string (URL) · optional as a query param, but effectively required when storage_mode=external and no endpoint is configured in 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://

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&storage_mode=external&storage_endpoint=https://s3.us-east-2.amazonaws.com

storage_bucket

string (URL) · optional as a query param, but effectively required when storage_mode=external and no bucket is configured in 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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&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 (.)

Request URL example (unencoded for readability):

https://api.screenshotscout.com/v1/capture?access_key=YOUR_ACCESS_KEY&url=https://example.com/&storage_mode=external&storage_object_key=users/acme/homepage-latest

Screenshot Options

On this page