Getting Started

ScreenshotAPI is a simple API that allows you to take programmatic screenshots of any website with ease. Screenshots can be saved as JPEG, PNG, WebP, and even PDF! We provide plenty of options.

Render a Screenshot (GET)

GET https://shot.screenshotapi.net/screenshot?token=TOKEN&url=URL&[OPTIONS]

The following options for the API call are:

TOKEN: The TOKENor your API key should be replaced by your real ScreenshotAPI API, you can find your API key after you Sign Up or Log In to the service via the Dashboard page.

Note: If for any reason you need to get a new API key, simply click "Roll API Key" in the "Settings" card on the Dashboard. This will issue you a fresh API key and revoke access from the previous key.

URL: Website URL for the site you would like to render for the screenshot. We support a wide variety of websites types, such as single page apps, very long-content, and sites that require lazy loading or delays ensuring accurate and complete screenshots of these unique sites.

OPTIONS: Options indicates the different URL parameters keys and values that can be used to render your "perfect" screenshot. All the options for screenshots will be detailed below.

Note: Default options for the screenshot will be shown in the Options table below.

Example

GET https://shot.screenshotapi.net/screenshot?token=TOKEN&url=https://apple.com

This will render the following png image output when you paste in the above string into your browsers URL bar (replacing TOKEN with your API key):

Render a Screenshot (POST)

POST https://shot.screenshotapi.net/screenshot

POST mode accepts the exact same parameters in the request body, but you need to use a JSON.

Request Options

get
Request Options

https://shot.screenshotapi.net/screenshot?token=TOKEN&url=https://apple.com
Request
Response
Request
Path Parameters
file_type
optional
string
File type for the file (If output is not set to json), the options include PNG, JPG, WebP, and PDF. The default is PNG
omit_background
optional
boolean
Omit background (If using PNG as the file_type only) removes the background from websites with a basic white background and makes it transparent. Default is false.
destroy_screenshot
optional
boolean
If true, the screenshot will not be stored on our server after render. The resulting screenshot (or PDF) must be deleted (destroyed) when it's rendered as it will not be available again. Default is false
fail_on_error
optional
boolean
If fail on error is set to true, then the API will return an error if the render encounters a 4xx or 5xx status code. Default is false
logitude
optional
number
The longitude to use with the browser's Geolocation API. Default is null
latitude
optional
number
The latitude to use with the browser's Geolocation API. Default is null
proxy
optional
string
Use an address for a proxy server for the request. Example: address:port or username:[email protected]:port. Default: ''
no_cookie_banners
optional
string
Block or hide cookie banners on websites as the request loads before render. Default is false
block_ads
optional
boolean
Block ad requests from common and popular ad-networks from loading the request before the render. Default is false
headers
optional
string
Sets the header or headers when the request is being loaded before the render. This works for single or multiple headers. Example: X-HEADER: value; X-OTHER_HEADERL otherValue;. Default is ''
cookies
optional
string
Sets the cookie or cookies when the request is being loaded before the render. This works for single or multiple cookies. Example: cookie=value;otherCookie=otherValue;. Default is ''
scroll_to_element
optional
string
Target a specific element for the browser to scroll to before the render. This is useful if a given element is only loaded in the viewport. Default is ''
selector
optional
string
Specify the target for the render based on a element with a matching selector. If the element is not found, a render of the results is still returned. Example: div > .main-navigation > .logo. Default is ''
css
optional
string
CSS code injected into the render. Default is ''
css_url
optional
string
URL for CSS code injected into the render. Default is ''
ttl
optional
integer
TTL (Time to Live) sets the number of seconds to keep a rendered screenshot (or PDF) in the cache. Default is 30 days or 2592000 seconds
user_agent
optional
string
Sets the User-Agent string for the render for a particular request. Default is ''
accept_languages
optional
string
Sets the Accept-Language header on the request for the specified URL rendered. Default isen-US,en;q=0.8
delay
optional
integer
Time delay in milliseconds (ms) before the screenshot is rendered from the browser instance (this includes PDFs). Default is 0
thumbnail_width
optional
integer
The width in pixels of the thumbnail generated from the render. If not set, the fallback behavior is the outputted screenshot. Default is null
output
optional
string
Set the output of the results from the render. The output can be either JSON or the raw image captured. Default is image
fresh
optional
string
Take a fresh screenshot or render (or PDF) vs. getting the version cached version within the app's storage. Default is false
lazy_load
optional
boolean
If lazy load is set to true, the browser will cross down the entire page to ensure all content is loaded in the render. Default is false
full_page
optional
boolean
Capture the full page of a website vs. the scrollable area that is visible in the viewport upon render. Default is false
retina
optional
boolean
Retina or a high definition equivalent for a device that sets the pixel ratio to 2X. This option will cause the screenshot processing time to go up due to processing of the larger images. Default is false
height
optional
integer
Viewport height in pixels of the browser render. Default is 867
width
optional
integer
Viewport width in pixels of the browser render. Default is 1680
custom_html
optional
string
Provide custom HTML that should be rendered. This will override the URL option and take a screenshot of the following HTML output. Default is ''
url
required
string
The URL of the website for the screenshot / render
token
required
string
Your API key for Screenshot API
Response
200: OK
If output is set to json the following response will be given. Otherwise, output is set to image, the rendered image data will be returned.
{
screenshot "https://screenshotapi-dot-net.storage.googleapis.com/google_com_adcc8c63541a.png"
url "https://google.com"
output "json"
file_type "png"
}

Errors

In rare circumstances the API may encounter an "Error 524" from Cloudflare. This is due to a timeout between the ScreenshotAPI API and our servers due to auto-scaling. If you see this error please just try your request again.

Quota

With each API call the following quota headers are sent.

X-Quota-Limit
X-Quota-Remaining
X-Quota-Reset-At
X-Quota-Limit

The total number of screenshots you can take per month

X-Quota-Remaining

The number of screenshots you can still make this month

X-Quota-Reset-At

A unix timestamp of when the quota resets (the first of each month)

Query Builder

Use our Query Builder to explore our API. (If you are logged in your API key is automatically added). To easily view all the screenshot options in an interactive builder to ensure you have your ideal screenshot dialed in.

You can check out the Query Builder here: https://app.screenshotapi.net.

Code Examples

Below is sample code for the following languages: Node.JS, PHP, Go, Java, Python, and Ruby.

If you need assistance integrating into our API with a given language please contact us.

NodeJS
PHP
Go
Java
Python
Untitled
NodeJS
var fs = require('fs')
var request = require('request');
// @param {String} token - String containing your API Key
// @param {String} url - Encoded URI string container the URI you're targeting
// @param {Integer} width - Integer indicating the width of your target render
// @param {Integer} height - Integer indicating the height of your target render
// @param {String} output - String specifying the output format, "image" or "json"
var token = 'Your API Key';
var url = encodeURIComponent('https://google.com');
var width = 1920;
var height = 1080;
var output = 'image';
// Construct the query params and URL
var query = "https://shot.screenshotapi.net/screenshot";
query += `?token=${token}&url=${url}&width=${width}&height=${height}&output=${output}`;
// Call the API and save the screenshot
request.get({url: query, encoding: 'binary'}, (err, response, body) => {
fs.writeFile("screenshot.png", body, 'binary', err => {
if (err) {
console.log(err);
} else {
console.log("The file was saved!");
}
});
});
PHP
// @param {String} $token - String containing your API Key
// @param {String} $url - Encoded URI string container the URI you're targeting
// @param {Integer} $width - Integer indicating the width of your target render
// @param {Integer} $height - Integer indicating the height of your target render
// @param {String} $output - String specifying the output format, "image" or "json"
$token = 'Your API Key';
$url = urlencode('https://google.com');
$width = 1920;
$height = 1080;
$output = 'image';
// Construct the query params and URL
$query = "https://shot.screenshotapi.net/screenshot";
$query .= "?token=$token&url=$url&width=$width&height=$height&output=$output";
// Call the API
$image = file_get_contents($query);
// Save the screenshot
file_put_contents('./screenshot.png', $image);
Go
package main
import (
"fmt"
"io"
"io/ioutil"
"net/http"
url2 "net/url"
"os"
)
func main() {
// @param {String} token - String containing your API Key
// @param {String} url - Encoded URI string container the URI you're targeting
// @param {Integer} width - Integer indicating the width of your target render
// @param {Integer} height - Integer indicating the height of your target render
// @param {String} output - String specifying the output format, "image" or "json"
token := "Your API Key"
url := url2.QueryEscape("https://google.com")
width := 1920
height := 1080
output := "image"
// Construct the query params and URL
query := "https://shot.screenshotapi.net/screenshot"
query += fmt.Sprintf("?token=%s&url=%s&width=%d&height=%d&output=%s",
token, url, width, height, output)
// Call the API
resp, err := http.Get(query)
if err != nil {
panic(err)
}
defer resp.Body.Close()
// Raise error if call was unsucessfull
if resp.StatusCode != 200 {
errorBody, _ := ioutil.ReadAll(resp.Body)
panic(fmt.Errorf("error while calling api %s", errorBody))
}
// Save the screenshot
file, err := os.Create("./screenshot.png")
if err != nil {
panic(err)
}
defer file.Close()
_, err = io.Copy(file, resp.Body)
if err != nil {
panic(err)
}
}
Java
package main;
import java.io.FileOutputStream;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.URL;
import java.net.URLEncoder;
public class Main {
public static void main(String[] args) {
try {
// @param {String} $token - String containing your API Key
// @param {String} $url - Encoded URI string container the URI you're targeting
// @param {Integer} $width - Integer indicating the width of your target render
// @param {Integer} $height - Integer indicating the height of your target render
// @param {String} $output - String specifying the output format, "image" or "json"
String token = "Your API Key";
String url = URLEncoder.encode("https://google.com");
int width = 1920;
int height = 1080;
String output = "image";
// Construct the query params and URL
String query = "https://shot.screenshotapi.net/screenshot";
query += String.format("?token=%s&url=%s&width=%d&height=%d&output=%s",
token, url, width, height, output);
URL apiUrl = new URL(query);
// Call the API and save the screenshot
InputStream inputStream = apiUrl.openStream();
OutputStream outputStream = new FileOutputStream("./screenshot.png");
inputStream.transferTo(outputStream);
inputStream.close();
outputStream.close();
} catch(Exception ex) {
ex.printStackTrace();
}
}
}
Python
import urllib.parse
import urllib.request
import ssl
ssl._create_default_https_context = ssl._create_unverified_context
# @param {String} $token - String containing your API Key
# @param {String} $url - Encoded URI string container the URI you're targeting
# @param {Integer} $width - Integer indicating the width of your target render
# @param {Integer} $height - Integer indicating the height of your target render
# @param {String} $output - String specifying the output format, "image" or "json"
token = "Your API Key"
url = urllib.parse.quote_plus("https://google.com")
width = 1920
height = 1080
output = "image"
# Construct the query params and URL
query = "https://shot.screenshotapi.net/screenshot"
query += "?token=%s&url=%s&width=%d&height=%d&output=%s" % (token, url, width, height, output)
# Call the API
urllib.request.urlretrieve(query, "./screenshot.png")

Support

At ScreenshotAPI we are there for you. We are developers ourselves and strive to ensure you have a great screenshot experience. If you need help at any point please contact us at [email protected] or use the chat bubble in the bottom right of your screen.

The ScreenshotAPI Team -- Andrew, Michael, Tom, and Henry