API Documentation

Overview

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

https://api.screenshots.cloud/v1/[API_KEY]/[TOKEN]/?[PARAMETERS]
PartDescription
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.

API Implementations

Packages

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": "openai.com/research", 
	"width": 800
});

If you wish to download the image the simplest method would be to use a http client such as request or the built in http library. Example below:


// make sure to npm install request or yarn add request to your project first
const request = require('request');

// ...previous code from above example
request.get(screenshotUrl, {encoding: 'binary'}, function(error, response, imageBody) {
	let screenshotResult = imageBody;

	// if you want to save it to disk
	require('fs').writeFileSync('screenshot.png', screenshotResult, 'binary');
});

Parameters

ParameterDefaultDescription
urlRequired. The website address that you want to take a screenshot of, with or without http:// or https://.
browserfastestWhich browser to run the request on. chrome for Google Chrome, firefox for Mozilla Firefox, fastest to run the request on both browsers and return the request from the browser which renders the screenshot fastest. Defaults to fastest.
width1920Width of the thumbnail. We resize from the viewport_width to this width value after the screenshot has been captured. 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)If true capture a full length screenshot of the requested page. If false capture only the viewport area specified in viewport_width and viewport_height. 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. Ignored if force parameter is true.
forcefalseForce a new screenshot to be taken with no cache.
user_agentRecent Firefox or Chrome 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. For example if the website header returns "Cookie: user_id=foo; session=bar;" as its cookie you can use the value string of the cookie "user_id=foo; session=bar;" as the cookie value for your screenshot request.
disable_javascriptfalseDon't execute javascript on this page. Forces browser=firefox.
disable_imagesfalseDon't download images on this page. Forces browser=firefox.
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. Forces browser=chrome.
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.

Beta Login Parameters

These special parameters when used together allow you to log in to a website before taking the screenshot. The username and password are currently added to the resulting screenshot URL in plaintext (except for our NodeJS implementation which encrypts credentials, this will expand to most implementations in the future) so for security reasons we highly recommend that you download the resulting image and host it on your own service while using this feature.

ParameterDefaultDescription
login_url Beta Required for logging in to the website before you screenshot. The url of the website where you can log in e.g. https://www.reddit.com/login.
login_usernameBeta Required for logging in to the website before you screenshot. E-mail or username required to log in to the website.
login_password Beta Required for logging in to the website before you screenshot. The password used to log in to the website.
login_debugfalse Beta If set to true this will produce a screenshot that does not visit to your url so you can see any errors that occured trying to log in.

Response Headers

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

HeaderDescription
AgeThe time in seconds this request has been cached, 0 for fresh.
X-BrowserThe browser and browser version that fulfilled the request.
X-In-Browser-StatusThe HTTP Status Code returned by the requested 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.

Error Handling

If the website of the screenshot you're taking is temporarily unavailable we will send a screenshot of the error page and not cache the screenshot, you may check the X-In-Browser-Status header if you're downloading the screenshot and retry the request. If you're displaying the generated screenshot urls directly on your website we'll periodically keep retrying the request until a valid screenshot is available.

Frequently Asked Questions

How do I screenshot content is not publicly 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.
I want to screenshot only a particular part of the page? Can I do that?
Yes you can! You can use clip_selector to find a selector to screenshot, it will screenshot only that part of the page. Need to find the unique CSS selector for your screenshot? In most modern browsers you right click on the element you want to screenshot and click Inspect, it will open the development console of your browser and highlight the element, right click on that element and find the Copy menu and Copy Selector, you should now have a unique selector you can use to screenshot a particular area!
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 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 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 will allow you to go over your plan limit to ensure continued service, any screenshots over 100% of your allocation will be billed at the plan overage rate at the end of the billing period. 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.

Ready to get started?

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