API Documentation


To make a screenshot request to the ScreenshotsCloud API use the following format:

API_KEYYour ScreenshotsCloud API key, to obtain your key sign in to your account. If you do not have an account yet please register.
TOKENThe request token is a HMAC SHA1 hash generated from your request parameters and your API Secret. Your ScreenshotsCloud API secret can be obtained by signing in to your account. If you do not have an account yet please register.
PARAMETERSA URL query string with screenshot options including the url of the page to be screenshotted. See API Options below for the list.



We have API implementations already written for you to use in a number of languages. If you have need for an implementation in a language not listed here please contact support@brushd.com.

Install via npm or GitHub

npm install screenshotscloud

Or if you prefer yarn

yarn add screenshotscloud

Once installed you can generate screenshot urls as follows:

const ScreenshotsCloud = require('screenshotscloud');

const SCREENSHOTSCLOUD_KEY = 'my-key-generated-at-screenshots-dot-cloud';
const SCREENSHOTSCLOUD_SECRET = 'mysecretstringgeneratedatscreenshotsdotcloud';

const screenshotscloud = ScreenshotsCloud(SCREENSHOTSCLOUD_KEY, SCREENSHOTSCLOUD_SECRET);

const screenshotUrl = screenshotscloud.screenshotUrl({
	"url": "bbc.com/news", 
	"width": 800


urlRequired. The website address that you want to take a screenshot of.
width1920Width of the thumbnail. This option is only valid for png or jpg format options.
viewport_width1920Width of the browser viewport this is the actual width of the page before we resize it for the thumbnail.
viewport_height(1320)Height of the browser viewport, if you do not give this parameter we will calculate it for you based on viewport_width in 16:10 ratio.
full_pagefalse (true if format=pdf)Capture a full length screenshot of the requested page. If the format is pdf this option will always be true.
formatpngValid options are jpg, png or pdf.
quality95 (if format=jpg)Set the jpeg quality of the screenshot if jpg is set as the format.
delay100Amount of time to wait in milliseconds before taking a screenshot of the page after it is fully loaded. Maximum 60000 (1 minute), minimum 100.
cache_time2592000Amount of time in seconds to wait before taking a fresh screenshot for the same request. Maximum 2592000 (30 days), minimum 1.
forcefalseForce a new screenshot to be taken with no cache.
user_agentRecent Firefox User AgentSet the user agent this screenshot will identify as. Useful for identifying as a mobile or tablet browser or to identify as a specific browser if the website pretends it needs Internet Explorer.
authorizationIf your screenshot request needs to send an Authorization header add it with this parameter. e.g. Basic YWxhZGRpbjpvcGVuc2VzYW1l.
trimfalseTrim the excess space around the resulting screenshot using the most top left pixel color, useful for SVG's.
languageenAccept-Language header customization for websites that support it, set ja for Japanese, de for German etc.
cookieSemi colon separated list of cookies e.g. fruit=apple; drink=tea
disable_javascriptfalseDon't execute javascript on this page.
disable_imagesfalseDon't download images on this page.
timeout300000Amount of time in milliseconds to wait before taking the screenshot anyway. Maximum 300000 (5 minutes).
mobilefalseShortcut to set pixel_ratio, user_agent, viewport_width, viewport_height and width to that of the latest iPhone.
pixel_ratio1Multiplier that sets the pixel density of the page relative to the resolution, useful for taking retina screenshots (2).
hide_selectorAccepts valid DOM selector (e.g. .wantedselector). Elements that match the selector you provide will be hidden from view (display: none).
click_selectorAccepts valid DOM selector (e.g. .wantedselector[attribute]). Send a click event to all elements matching your selector.
hover_selectorAccepts valid DOM selector (e.g. #wantedselector). Mouse will be hovered over the first instance of the selector you specify.
wait_selectorAccepts valid DOM selector (e.g. .valid_selector > .another_class). We will not take the screenshot until .valid_selector appears on this screen and is not display:none; or timeout is reached.
clip_selectorAccepts valid DOM selector (e.g. .valid_selector:not(div)). Rendered screenshot will only display contents of DOM selector. This option is only valid for png or jpg format options.

Response Headers

If you are downloading the screenshot directly you may find some of our HTTP response headers useful.

AgeThe time in seconds this request has been cached, 0 for fresh.
X-In-Browser-StatusThe HTTP Status Code of your screenshot url.
X-In-Browser-TimeThe time this request took to render in milliseconds.
X-Initial-Page-Request-TimeThe time this request took to recieve the initial requested page in milliseconds.
X-Page-Open-TimeThe time this request took to reach the onload javascript event in milliseconds.
X-Processing-TimeThe time this request took to process through our complete rendering system in milliseconds.
X-CacheWhether the requested screenshot was cached or not. HIT or GRACE for cached, MISS for fresh. See the force parameter to force the request to always be fresh.

Frequently Asked Questions

Do I have to generate a unique token for every request?
Yes, if the token wasn't unique to the request it would be possible for an unauthorized user to manipulate the URL to create new screenshot requests.
My screenshot has a popup element or other element I need to click, how do I do that?
We have a couple of ways to accomplish this. You will need to look for the CSS selector that matches the element that is appearing in the way. click_selector will send a click even to the selector you specify. hide_selector will hide the entire element from the page.
I need to hover over something on the page for my screenshot, how do I do that?
You can use hover_selector to instruct the mouse to hover over a certain element on the page.
I just need to screenshot a particular part of the page? Can I do that?
You can use clip_selector to find a selector to screenshot, it will screenshot only that part of the page.
I want to wait for a certain part of the page to appear before taking a screenshot, can I make that happen?
You can use wait_selector to wait for a selector to screenshot, it will wait until that selector appears before rendering the screenshot. Please check your timeout parameter too!
I don't see an implementation in the programming language I use, what should I do?
You can either find your languages HMAC SHA1 method and use it to construct the token nessesary to generate a screenshot, alternatively you could use our Shell Script implementation and use your language to call the script. Finally you can contact us at support@brushd.com to discuss your requirements. We may be able to produce an implementation for you.
How do I request a new screenshot with no caching?
Use the force parameter to ensure your request is fresh.
What's a unique screenshot?
A unique screenshot is the first request made by the url you have generated within the cache_time period (default 30 days).
Do I have to pay per impression?
No, only when a new screenshot is generated by our system (following whatever cache_time you have set, default 30 days).
What happens if I go over my plan limit?
We will notify you via e-mail alerts to the e-mail address you registered with before you are about to reach your limit (80%, 90%, 95%, 100% and 125%). We allow you to reach over 5% of your limit with no additional fees. Please consider upgrading if you need more screenshots!
How do I cancel?
You can cancel any time by pressing the Cancel Account button in your account dashboard.
How do I contact support?
You can e-mail us any time at support@brushd.com or contact us through chat.
My screenshot request requires a login, what can I do?
If you are using Basic Auth you can use the authorization parameter. While we currently have no way to fill forms we have the cookie parameter you can use should you already know what values to use.
How do I screenshot content is not internet accessible?
We recommend using a secure tunnelling program that will allow you to have an internet accessible address. This will allow our screenshot service to access your content for the screenshot. We personally use ngrok but we also recommend evaluating Forward, PageKite and Portmap.io.

Ready to get started?

Start your free trial now
Full screenshot creator playground available inside!