Screenshot API Documentation
The Clearshot Screenshot API has been built from the ground up to provide a simple, reliable, cost-effective and fast API that any developer/company can use to take perfect website screen captures. Included are a range of features to customize your requests to suit your use case.
The following documentation will provide detailed information about API usage, request parameters, responses and available endpoints. Through-out, useful examples are provided to assist you in getting started quickly and easily.
To get started fast, here are some examples you can use/test. You’ll need to get a token here.
curl https://app.clearshotapi.com/api/screenshot? \ url=https://apple.com \ &response_type=image \ &access_token=__YOUR_ACCESS_TOKEN__
API Access Key & Authentication
Clearshot provides API access through HTTPS GET and POST endpoints.
All calls to the API need to be authorized using a valid access token which can be managed on the Clearshot admin panel.
For GET requests, the access token should be passed via the query string. Here is an example:
For POST requests, the access token should be passed in the header data.
Listed below are the available parameters for the screenshot API.
To use a parameter, include the parameter and a value in the query string or POST data.
Here’s an example with providing viewport sizing parameters in a GET request:
||A valid API access token is required to make requests. You can manage your access tokens in the admin panel.|
||The complete URL including protocol of the web page you want to capture.|
|mode||fullpage||Choose the capture mode. Either
|height||1080||The height in pixels of the viewport to capture. This is ignored if
|width||1920||The width in pixels of the viewport to capture.|
|response_type||image||Choose a response type.
|format||jpeg||The format of the image captured. Chose either
|delay||0||The delay in seconds (after page load) to wait before capturing a screenshot. Choose from 0 to 10 seconds (maximum).|
|file_name||You can provide a filename which will be used when storing the screenshot.|
|user_agent||Set a User Agent header to be used when capturing a screenshot, to emulate a device or browser type. Ensure the User Agent string is URL encoded to be used correctly. You can find a list of user agents sorted by device/software/layout engine here.|
|block_ads||false||Blocks common advertising networks to prevent ads from being captured in screenshots. Set this to true or false.|
|accept_lang||Set the Accept Language header on requests to the target page to capture screenshots in the specified language. More information is available here.|
|grayscale||false||Apply a grayscale filter to the captured screenshot.|
|css||CSS styling string to be injected onto the target page. The string must be URL encoded to be properly parsed and injected.|
If an API request fails, an HTTP error code will be returned. The error codes below provide a description of why the error occurred.
For successful API requests, you can expect the HTTP code
Common API Errors:
||Invalid parameters or the target URL provides an error.|
||An invalid API access key was supplied.|
||The given user account has reached its monthly allowed request volume.|
||The given API endpoint is not supported on the current subscription plan.|
||An internal error occurred.|
Render Modes Explained
modeparameter allows you to define the size of the screenshot you will be capturing. Below we’ll run through the 2 different modes and how they operate.
Full page or
fullpage as the mode parameter value is the default mode.
As the name suggests, this mode captures a screenshot of the entire target page. The height of the image is determined by the page length. Whilst height is automatic, you can pass a
width parameter to determine the width of the page capture.
When capturing full page screenshots, we recommend using the
jpeg format (instead of
png) to avoid very large file sizes and slower image loading performance.
Viewport mode restricts the render sizing to a specified set of dimensions. To enable viewport capture mode, set
mode to the value:
The viewport dimensions (in pixels) are passed to the API via the
The default viewport size is 1280×1024.
Note that when providing viewport dimensions, this will affect the webpage render sizing and can trigger responsive breakpoints in the target URLs styling. As a result, the returned image may not always be the exact size of the dimensions passed in the request.
This mode allows you to capture a specific element on the page. To specify what element you wish to capture, simply set your
element and provide a CSS selector to
The default viewport for element capture is 1280x1024px.
Below are code examples for a range of languages. Implementation in a language/framework that is not listed is usually as simple as using your favourite HTTP request package to make a GET or POST request and receive the response. Should you have any questions about implementation, feel free to reach out to our support team.