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
orjpg
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
.