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 forjpg),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 appropriateContent-Type. We will also return the screenshot URL via theScreenshot-Scout-Screenshot-URLresponse header. Ifcache=true, we will also return the screenshot expiration date and the cache status (HIT,MISS) viaScreenshot-Scout-Screenshot-URL-Expires-AtandScreenshot-Scout-Cache-Statusresponse headers respectively.json: Returns a JSON object with thescreenshot_urlproperty containing the URL of the screenshot. Ifcache=true, the JSON object will also contain the screenshot expiration date and the cache status (hit,miss) in thescreenshot_url_expires_atandcache_statusproperties 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
-90and+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
-180and+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:Valueform
POST request body example:
{
"url": "https://example.com/",
"headers": ["Accept-Language:en", "X-Experiment:variantA"]
}Navigation & timing
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 theDOMContentLoadedevent (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"
}navigation_timeout
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:
1920ifdeviceis not provided. Ifdeviceis provided, the defaultdevice_viewport_widthis 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:
1080ifdeviceis not provided. Ifdeviceis provided, the defaultdevice_viewport_heightis 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
- For
-
Allowed values:
screen: emulate normal screen media, which is the regular option for screenshotsprint: emulate print media; when used, it applies@media printCSS, 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 websitelight: force light color schemedark: 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 to240minimum,2000maximum) - 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
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
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_heightmust be<= 64,000,000pixels
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_heightmust be<= 64,000,000pixels
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
jpgorgif:#FFFFFF - For other formats: transparent
- For
-
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:
letterlegaltabloida3a4a5a6
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, orcm(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:
0ifpdf_marginis not provided; otherwise, the default value is derived frompdf_margin - Allowed values: non-negative CSS length in units:
px,in,mm, orcm(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:
0ifpdf_marginis not provided; otherwise, the default value is derived frompdf_margin - Allowed values: non-negative CSS length in units:
px,in,mm, orcm(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:
0ifpdf_marginis not provided; otherwise, the default value is derived frompdf_margin - Allowed values: non-negative CSS length in units:
px,in,mm, orcm(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:
0ifpdf_marginis not provided; otherwise, the default value is derived frompdf_margin - Allowed values: non-negative CSS length in units:
px,in,mm, orcm(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 rangesstart-endwherestart <= 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:
14400seconds (4 hours) - Allowed values:
14400–2592000seconds (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. Whenstorage_mode=external, you must configure your credentials in the panel. The endpoint, bucket, and region can either be configured in the panel, or via optionsstorage_endpoint,storage_bucket, andstorage_regionrespectively.
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"
}