Request Options

Credentials #

access_key #

Each request must have an access key to authenticate the API user. You can find it on the access page.

An example of the request URL with access_key:

https://api.screenshotone.com/take?url=https://apple.com&access_key=<your access key>

Result

signature #

A signature is optional. It is used for the singed requests.

You can force signing all requests access page.

Essentials #

url #

URL of the site to take a screenshot of. One of the HTML or URL parameters is required.

An example of the request URL with url=https://www.youtube.com/feed/explore:

https://api.screenshotone.com/take?url=https://www.youtube.com/feed/explore&access_key=<your access key>

Result

html #

HTML you want to render. One of the HTML or URL parameters is required.

An example of the request URL with html=<h1>Hello, world!</h1>:

https://api.screenshotone.com/take?html=<h1>Hello,%20world!</h1>&access_key=<your access key>

Result

selector #

A CSS-like selector of the element to take a screenshot of. It is optional.

If the selector is specified and error_on_selector_not_found=true, the error will be returned if the element by selector is not visible or it took more than timeout seconds to render it, but not more than 30 seconds.

An example of the request URL with selector=.content:

https://api.screenshotone.com/take?selector=.content&url=https://scalabledeveloper.com/posts/context-in-go/&access_key=<your access key>

Result

The same page without selector:

https://api.screenshotone.com/take?url=https://scalabledeveloper.com/posts/context-in-go/&access_key=<your access key>

Result

format #

Available response formats:

• png
• jpeg or jpg
• webp
• gif
• jp2
• tiff
• avif
• heif

Default value is jpg.

An example of the request URL with format=jpeg (an alias for format=jpg):

https://api.screenshotone.com/take?format=jpeg&url=https://apple.com&access_key=<your access key>

Result

Full page #

full_page #

To take the screenshot of the full page, set full_page=true.

Default value is false.

When full_page is set to true, [#full_page_scroll] is automatically set to true, until you override it. It is done to make sure that all lazy loaded images are requested and rendered.

An example of the request URL:

https://api.screenshotone.com/take?full_page=true&url=https://netflix.com&access_key=<your access key>

Result

full_page_scroll #

If set to true, scrolls to the bottom of the page and back to the top. Default value is false.

When full_page is set to true, full_page_scroll is automatically set to true, until you override it. It is done to make sure that all lazy loaded images are requested and rendered.

Viewport #

viewport_width #

The width of the browser viewport (pixels).

The browser’s viewport is the window area where you can see the web content.

Default value is 1280.

An example of the request URL with viewport_width=1920 and viewport_height=1080:

https://api.screenshotone.com/take?viewport_width=1920&viewport_height=1080&url=https://apple.com&access_key=<your access key>

Result

viewport_height #

The height of the browser viewport (pixels).

The browser’s viewport is the window area where you can see the web content.

Default value is 1024.

An example of the request URL with viewport_width=1920 and viewport_height=1080:

https://api.screenshotone.com/take?viewport_width=1920&viewport_height=1080&url=https://apple.com&access_key=<your access key>

Result

device_scale_factor #

Set the device scale factor, think of it as DPR (Device Pixel Ratio). Acceptable value is one of:

• 1
• 2
• 3

Set 2 if you need to render a screenshot with a higher pixel density like Apple’s Retina Display.

An example of the request URL with device_scale_factor=1:

https://api.screenshotone.com/take?device_scale_factor=1&url=https://apple.com&access_key=<your access key>

Result

An example of the request URL with device_scale_factor=2:

https://api.screenshotone.com/take?device_scale_factor=2&url=https://apple.com&access_key=<your access key>

Result

Image #

image_quality #

Render image with specified quality. Available for the next formats:

• jpeg (jpg)
• webp
• png
• tiff
• jp2
• avif
• hei

Allowed range is between 0 and 100. Default value is 80.

An example of the request URL with image_quality=10:

https://api.screenshotone.com/take?format=webp&image_quality=10&url=https://apple.com&access_key=<your access key>

Result

image_width #

The image_width and image_height parameters allow you to create a thumbnail of the screenshot, rendered HTML or PDF.

By default image_width = viewport_width and image_height = viewport_height.

If you specify image width and height parameters, the API will resize a screenshot, preserving the aspect ratio. The image will be resized to be as large as possible while ensuring its dimensions are less than or equal to the image width and height specified.

If you omit one of the parameters, the other is computed automatically, preserving the aspect ratio

An example of the request with image_width=500:

https://api.screenshotone.com/take?image_width=500&url=https://example.com/&access_key=<access key>

image_height #

The image_width and image_height parameters allow you to create a thumbnail of the screenshot, rendered HTML or PDF.

By default image_width = viewport_width and image_height = viewport_height.

If you specify image width and height parameters, the API will resize a screenshot, preserving the aspect ratio. The image will be resized to be as large as possible while ensuring its dimensions are less than or equal to the image width and height specified.

If you omit one of the parameters, the other is computed automatically, preserving the aspect ratio

An example of the request with image_width=500&image_height=400:

https://api.screenshotone.com/take?image_width=500&image_height=400&url=https://example.com/&access_key=<access key>

omit_background #

Render a transparent background for the image. Works only if the site has not defined background color. Available for the following response formats:

• png
• webp

Default value is `false.

Set omit_background=true to take a screenshot with the transparent background.

Customization #

hide_selectors #

The hide_selectors option allows hiding elements before taking a screenshot. You can specify as many selectors as you wish. All elements that match each selector will be hidden by setting the display style property to none !important.

An example of the request URL with hide_selectors=.a&hide_selectors=.b:

https://api.screenshotone.com/take?hide_selectors=.a&hide_selectors=.b&url=https://example.com/&access_key=<your access key>

scripts #

scripts parameter allows to inject custom JavaScript and customize the page behavior.

An example of the request URL with scripts=document.body.innerHTML="Hello, world!":

https://api.screenshotone.com/take?scripts=document.body.innerHTML="Hello,%20world!"&url=https://example.com/&access_key=<your access key>

Result

scripts_wait_until #

The default value of scripts_wait_until is [] — nothing, no wait at all.

The scripts_wain_until option allows you to wait until a given set of events after the scripts were executed. You need to use in case, if your script might trigger page reloading, like:

window.location = 'https://example.com';

It accepts the same values as wait_until and can have multiple values:

• load: the navigation is successful when the load even is fired;
• domcontentloaded: the navigation is finished when the DOMContentLoaded even is fired;
• networkidle0: the navigation is finished when there are no more than 0 network connections for at least 500 ms;
• networkidle2: consider navigation to be finished when there are no more than 2 network connections for at least 500 ms.

The parameter accepts many values. It means that screenshots will be taken after all events occur altogether.

An example of the request with scripts_wait_until=networkidle2&scripts_wait_until=domcontentloaded:

https://api.screenshotone.com/take?scripts_wait_until=networkidle2&scripts_wait_until=domcontentloaded&url=https://example.com/&access_key=<access key>

styles #

styles parameter allows to inject custom styles and customize the page. It might help generate beautiful images for the Open Graph protocol.

An example of the request URL with styles=h1{color: red;}:

https://api.screenshotone.com/take?styles=h1{color:%20red;}&url=https://example.com/&access_key=<your access key>

Result

A screenshot without styles for comparison:

Result

Blocking #

block_cookie_banners #

Blocks cookie banners, GDPR overlay windows, and other privacy-related notices. Default value is false.

It is useful when you want to take “clean” screenshots.

An example of the request URL with block_cookie_banners=true:

https://api.screenshotone.com/take?block_cookies=true&url=https://stackoverflow.com&access_key=<your access key>

Result

An example of the request URL with block_cookie_banners=false:

https://api.screenshotone.com/take?block_ads=false&url=https://stackoverflow.com&access_key=<your access key>

Result

block_chats #

Blocks chats like Crisp, Facebook Messenger, Intercom, Drift, Tawk, User.com, Zoho SalesIQ and many others. Default value is false.

It is useful when you want to take “clean” screenshots.

An example of the request URL with block_chats=true:

https://api.screenshotone.com/take?block_chats=true&url=https://screenshotone.com&access_key=<your access key>

Result

An example of the request URL with block_chats=false:

https://api.screenshotone.com/take?block_chats=false&url=https://screenshotone.com&access_key=<your access key>

Result

block_ads #

Blocks ads. Default value is false.

It is useful when you want to take “clean” screenshots or don’t want to generate a loss for advertisers.

An example of the request URL with block_ads=true:

https://api.screenshotone.com/take?block_ads=true&url=https://scalabledeveloper.com/posts/linux-kernel-coding-style/&access_key=<your access key>

Result

An example of the request URL with block_ads=false:

https://api.screenshotone.com/take?block_ads=false&url=https://scalabledeveloper.com/posts/linux-kernel-coding-style/&access_key=<your access key>

Result

block_trackers #

Block trackers. Default value is false.

It is useful when you don’t want to count screenshots as client visits in your analytics app.

Set block_trackers=true to disable all trackers.

block_requests #

Block requests by specifying URL, domain, or even a simple pattern like block_requests=*.example.com/*. You can specify the parameter multiple times like block_requests=example.com&block_requests=http://*.

Blocking requests by URL or domain can be used to test how the site responds when resources are not available. Or it might be used to speed up page loading.

Or, as an example, another way of blocking ads and trackers with block_requests=*.carbonads.com&block_requests=*.google-analytics.com:

https://api.screenshotone.com/take?block_requests=*.carbonads.com&url=https://scalabledeveloper.com/posts/linux-kernel-coding-style/&access_key=<access key>

Result

block_resources #

Blocks loading resources by type. Available resource types are:

• document
• stylesheet
• image
• media
• font
• script
• texttrack
• xhr
• fetch
• eventsource
• websocket
• manifest
• other

Blocking resources might be helpful when you need to optimize page loading speed before taking a screenshot.

You can specify multiple values as block_resources=stylesheet&block_resources=image:

https://api.screenshotone.com/take?block_resources=stylesheet&block_resources=image&url=https://screenshotone.com&access_key=<access key>

Result

Geolocation #

geolocation_latitude #

Set geolocation latitude for the request. Both latitude and longitude are required if one of them is set.

Take a screenshot from Eiffel Tower with accuracy in 50 meters geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50:

https://api.screenshotone.com/take?geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50&url=https://www.infobyip.com/browsergeolocation.php&access_key=<access key>

Result

geolocation_longitude #

Set geolocation longitude for the request. Both latitude and longitude are required if one of them is set.

Take a screenshot from Eiffel Tower with accuracy in 50 meters geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50:

https://api.screenshotone.com/take?geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50&url=https://www.infobyip.com/browsergeolocation.php&access_key=<access key>

Result

geolocation_accuracy #

Set the geolocation accuracy in meters.

Take a screenshot from Eiffel Tower with accuracy in 50 meters geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50:

https://api.screenshotone.com/take?geolocation_latitude=48.858184&geolocation_longitude=2.294720&geolocation_accuracy=50&url=https://www.infobyip.com/browsergeolocation.php&access_key=<access key>

Result

Request #

proxy #

You can use your custom proxy to take screenshots or render HTML with the proxy option.

It is suitable in many cases. For example, you might want to render a screenshot from the given location and check how the site renders for this location.

The https, http, socks4 and socks5 proxies are supported.

Example of the request:

https://api.screenshotone.com/take?proxy=socks5://127.0.0.1:1080&url=https://example.com/&access_key=<access key>

user_agent #

A user agent for the request. The default value is the latest version of the browser that Puppeteer uses.

An example with default user agent:

https://api.screenshotone.com/take?url=https://www.whatsmyua.info/&access_key=<access key>

Result

An example with specified user agent user_agent=screenshoter:

https://api.screenshotone.com/take?user_agent=screenshoter&url=https://www.whatsmyua.info/&access_key=<access key>

Result

authorization #

Set the Authorization header for the request.

Setting the authorization header is proper when you want to take a screenshot of the protected page by basic authentication or token.

For example, if use basic authentication with credentials like username:password, encode it to Base64 format dXNlcm5hbWU6cGFzc3dvcmQ= and then use set the value of the authorization header like authorization=Basic+dXNlcm5hbWU6cGFzc3dvcmQ=.

cookies #

Set cookies for the request in format <cookie-name>=<cookie-value>; Domain=<domain-value>; Secure; HttpOnly. You can specify multiple cookies.

An escaped query string might look like: cookies=name1=val1;+Domain=example.com;+Secure;+HttpOnly&cookies=name2=val2;+Domain=example.com;+Secure;+HttpOnly

headers #

Set extra headers for the request in the format of Header-Name:Header-Value

Headers can override all other previously implicitly set headers by options like cookies or authorization.

You can specify multiple headers at once headers=X-Header-1:Value-1&headers=X-Header-2:Value-2:

https://api.screenshotone.com/take?headers=X-Header-1:Value-1&headers=X-Header-2:Value-2&url=http://myhttpheader.com/&access_key=<access key>

Result

time_zone #

Sets time zone for the request. Available time zones are:

• America/Santiago
• Asia/Shanghai
• Europe/Berlin
• America/Guayaquil
• Europe/Madrid
• Pacific/Majuro
• Asia/Kuala_Lumpur
• Pacific/Auckland
• Europe/Lisbon
• Europe/Kiev
• Asia/Tashkent
• Europe/London

Default time zone is GMT +/- 00:00.

An example with time_zone=Europe/Madrid:

https://api.screenshotone.com/take?time_zone=Europe/Madrid&url=https://whatismytimezone.com/&access_key=<access key>

Result

Wait #

These are one of the most tricky parameters when rendering screenshots of a site. Read on how to wait until the page is ready if you are curious. Or use these wait options directly.

wait_until #

Use wait_until to wait until an event occurred before taking a screenshot or rendering HTML or PDF.

The default value of wait_until is ['load', 'domcontentloaded']. Allowed values are:

• load: the navigation is successful when the load even is fired;
• domcontentloaded: the navigation is finished when the DOMContentLoaded even is fired;
• networkidle0: the navigation is finished when there are no more than 0 network connections for at least 500 ms;
• networkidle2: consider navigation to be finished when there are no more than 2 network connections for at least 500 ms.

The parameter accepts many values. It means that screenshots will be taken after all events occur altogether.

An example of the request with wait_until=networkidle2&wait_until=domcontentloaded:

https://api.screenshotone.com/take?wait_until=networkidle2&wait_until=domcontentloaded&url=https://example.com/&access_key=<access key>

delay #

Specify the delay option in seconds to wait before taking a screenshot or rendering HTML or PDF.

It is suitable when the wait_until option does not work well for you, and you want to ensure that everything is ready.

The default value is 0. It can be more than 30 seconds.

An example of the request with delay=5:

https://api.screenshotone.com/take?delay=5&url=https://example.com/&access_key=<access key>

timeout #

Specify timeout (in seconds) of when to abort the request if screenshot or rendering is still impossible. The default and max value is 30.

An example of the request with delay=20:

https://api.screenshotone.com/take?timeout=20&url=https://example.com/&access_key=<access key>

Caching #

Screenshots are cached by the combination of all specified request options. And the cache_key option allows having different cached versions of the same screenshot.

Cached screenshots are not counted by quota and are not logged anywhere. They are served directly from the cache. Screenshots are cached in a combination of Cloudflare CDN and R2 storage (like Amazon S3).

cache #

The cache option enables or disables caching of a screenshot, rendering HTML, or PDF. The default value is false.

The false option forces disabling caching and always generate a free screenshot or render HTML or PDF without caching.

An example of the request with cache=false:

https://api.screenshotone.com/take?cache=false&url=https://example.com/&access_key=<access key>

cache_ttl #

The cache_ttl option (in seconds) hints at how long the cached screenshot should be stored. The minimum value is 14400 seconds (4 hours), and the maximum value is 2592000 seconds (one month).

An example of the request with cache_ttl=20000:

https://api.screenshotone.com/take?cache=true&cache_ttl=20000&url=https://example.com/&access_key=<access key>

cache_key #

Screenshots are cached by the combination of all specified request options. The cache_key option allows having different cached versions of the same screenshot.

An example of the request with cache_key=2022-07-14:

https://api.screenshotone.com/take?cache=true&cache_key=2022-07-14&url=https://example.com/&access_key=<access key>

Storing #

You can use any S3-compatible storage to store screenshots, rendered HTML or PDF to the configured S3 bucket.

store #

Default value is false. Use store=true to trigger upload of the taken screenshot, rendered HTML or PDF to the configured S3 bucket. Make sure you configured access to S3.

An example of the request with store=true:

https://api.screenshotone.com/take?store=true&url=https://example.com/&access_key=<access key>

storage_path #

The parameter is required if you set store=true. You must specify the key for the file, but don’t specify an extension, it will be added automatically based on the format you specified.

You can also specify “subdirectories” in the path part.

An example of the request with store_path=latest/example:

https://api.screenshotone.com/take?store=true&store_path=latest/example&url=https://example.com/&access_key=<access key>

storage_bucket #

You can override the default bucket you configured with storage_bucket=<bucket name>.

An example of the request with storage_bucket=temporary:

https://api.screenshotone.com/take?storage_bucket=temporary&store=true&store_path=latest/example&url=https://example.com/&access_key=<access key>

storage_class #

The default value is standard.

Storage class allows you to specify the object storage class.

Allowed values:

• standard;
• reduced_redundancy;
• standard_ia;
• onezone_ia;
• intelligent_tiering;
• glacier;
• deep_archive;
• outposts;
• glacier_ir.

An example of the request with storage_class=glacier_ir:

https://api.screenshotone.com/take?storage_class=glacier_ir&store=true&store_path=latest/example&url=https://example.com/&access_key=<access key>

Error options #

error_on_selector_not_found #

If a selector is specified and error_on_selector_not_found=true, the error will be returned if the element by selector is not visible or it took more than timeout seconds to render it, but not more than 30 seconds.

Default value is false.