Developer Docs

Making an API request

The url format for making a screenshot request to's API is:

And if you are using urlbox directly on a public facing website, you should use the authenticated request url format:


  • YOUR_API_KEY should be replaced by your actual urlbox API key which you can get by registering for an account.
    (If you have already registered, you can find your API Key by logging in to your account.)

  • GENERATED_TOKEN should be replaced by a hash which is generated server side by taking the HMAC SHA1 of the query string and signing it with your API Secret. This parameter is optional unless you have enabled the Force Authenticated Requests option in your dashboard.
    Example code is below to get you started in no time

  • FORMAT should be one of either png or jpg depending on which format you want the resulting image

    . You can also set format to pdf to generate a pdf from the URL
  • REQUEST_OPTIONS should be replaced by a query string that contains all of the options you want to set.
    A table of all options and their defaults are shown below

An example, valid urlbox url is shown below, with the following options:

  • format is set to png
  • url is set to
  • thumb_width is set to 600 pixels wide
  • ttl is set to 86400 seconds which is equivalent to 1 day, meaning the screenshot will be freshly generated once daily

And here is the authenticated version:

Simply putting this url as the src attribute in a normal img tag, the resulting image is: screenshot API showing a screenshot thumbnail of

Request Options

Below is a table listing all of the available options to the API.
Combine these options as parameters in the query string for e.g. ?

urlThe URL of the website you want to screenshot-
widthViewport width of the browser in pixels1280
heightViewport height of the browser in pixels1024
selectorTake a screenshot of the element that matches this selector. By default, if the selector is not found, Urlbox will take a normal viewport screenshot. If you prefer Urlbox to fail the request when the selector is not found, pass fail_if_selector_missing=true.-
fail_if_selector_missingFails the request if selector or wait_for elements are not found on the pagefalse
frameIf your target element specified by either the selector or wait_for option is inside an iframe, set a selector to the containing iframe here .e.g iframe:nth-child(1)-
thumb_widthWidth in pixels of the generated thumbnail, leave off for full-size screenshot-
block_adsBlocks requests from popular ad-networks from loading-
user_agentUser-Agent string used to emulate a particular client-
accept_langSets an Accept-Language header on requests to the target URLen-US
authorizationSets an Authorization header on requests to the target URL-
cookieSets a cookie on the request when loading the URL. E.g. OptIn=true. Can be set multiple times to set more than one cookie-
headerSets a custom request header when loading the URL. E.g. X-My-Header=SomeValue. Can be set multiple times to set more than one header-
delayAmount of time to wait in milliseconds before urlbox takes the screenshot-
wait_forWaits for the element specified by this selector to be present in the dom before taking a screenshot. By default Urlbox will take a screenshot if the wait_for element is not found. If you prefer Urlbox to fail the request when the wait_for element is not found, pass fail_if_selector_missing=true-
timeoutAmount of time to wait in milliseconds for the website at url to respond30000
full_pageSpecify whether to capture the full scrollable area of the websitefalse
skip_scrollEnabling skip_scroll will speed up renders by skipping an initial scroll through the page which is used to trigger any lazy loading elements.false
allow_infiniteBy default when Urlbox detects an infinite scrolling page, it does not attempt to continue scrolling until the bottom, as this could result in infinite scrolling! If you want to override this behaviour pass true for this option-
detect_full_heightSome pages have full-height backgrounds whose heights are set to 100% of the viewport. Due to the way Urlbox takes screenshots, this can cause the backgrounds to get stretched when making a full_page screenshot. If you are seeing this behaviour in your screenshots, pass true for this option.-
max_heightWhen Urlbox takes a full_page screenshot, the maximum height of each image section is set as 4096 pixels. If a site is greater than this value, Urlbox will start splitting the screenshot into sections. Sometimes it is worthwhile to experiment with this number4096
scroll_incrementWhen scrolling the page to trigger lazy loading elements, decide by how many pixels the page should be scrolled by. By default the scroll incrememnt is set to the browser viewport height. Some pages lazy loading elements however only trigger when the scroll increment is smaller than this e.g. 400px-
flashEnable the flash plugin for flash using websitesfalse
forceTake a fresh screenshot instead of getting a cached versionfalse
ttlShort for 'time to live'. Number of seconds to keep a screenshot in the cache. Note the default is also the maximum value for this option.2592000 (30 days)
uniqueYou can pass a unique string such as a UUID, hash or timestamp to have more control over when to generate a fresh screenshot. For example unique=20180624100403-
qualityJPEG only - image quality of resulting screenshot (0-100)80
disable_jsTurns off javascript on target url. This option will also disable full_page=true because it is hard to infer the full content height when javascript is turned off.false
retinaTake a 'retina' or high definition screenshot equivalent to setting a device pixel ratio of 2.0 or @2x. Please note that retina screenshots will be double the normal dimensions and will normally take slightly longer to process due to the much bigger image size.false
transparentIf a website has no background color set, the image will have a transparent background (PNG only)false
clickElement selector that is clicked before taking a screenshot e.g. #clickme would click the element with id="clickme". Can be used multiple times to simulate multiple sequential click events.-
hoverElement selector that is hovered before taking a screenshot e.g. #hoverme would hover over the element with id="hoverme"-
bg_colorHex code or css color string. Some websites don't set a body background colour, and will show up as transparent backgrounds with PNG or black when using JPG. Use this setting to set a background colour. If the website explicitly sets a transparent background on the html or body elements, this setting will be overridden.-
crop_widthCrop the width of the screenshot to this size in pixels-
hide_selectorComma delimited string of css element selectors that are hidden by setting their style to `display:none !important;`. Useful for hiding popups.-
hide_cookie_bannersAttempts to hide cookie banners from most websites-
click_acceptAttempt to click accept buttons in order to hide popups-
highlightWord to highlight on the page before capturing a screenshot-
highlightfgText color of the highlighted wordwhite
highlightbgBackground color of the highlighted wordred
latitudeLatitude used to emulate the Geolocation API-
longitudeLongitude used to emulate the Geolocation API-
accuracyHow accurate the Geolocation API should be in meters-
proxyPass in an address to a proxy server to make screenshot requests via that server i.e. [address]:[port]. If proxy authentication is needed: [user]:[password]@[address]:[port].-
downloadPass in a filename e.g. download=myfilename.png which sets the content-disposition header on the response. This will make the urlbox link a downloadable link and prompt the user to save the file as myfilename.png.-
use_s3Save the screenshot directly to the S3 bucket configured on your accountfalse
s3_pathThe s3 path, including subdirectories and the filename, to save the screenshot to in your S3 bucket. The extension (.png, .jpg or .pdf) will be provided automatically and should not be included in s3_path.-
s3_bucketOverride the configured s3 bucket that the screenshot will be saved to-

Frequently Asked Questions


Example Code

Sample code is available in the following languages: Node.js, Ruby, PHP, Python, Java and C#.
If you would like help integrating our API with your language please get in touch


Sample code to take website screenshots in Node.js

Check out our npm package here, and on github

// npm install urlbox --save

import Urlbox from 'urlbox';

// Plugin your API key and secret
const urlbox = Urlbox(YOUR_API_KEY, YOUR_API_SECRET);

// Set your options
const options = {
  url: '',
  thumb_width: 600,
  format: 'jpg',
  quality: 80

const imgUrl = urlbox.buildUrl(options);

// Now set it as the src in an img tag to render the screenshot
<img src={imgUrl} />


Sample code to take website screenshots in Ruby

# ruby gem coming soon
require 'openssl'
require 'open-uri'

def encodeURIComponent(val)
def urlbox(url, options={}, format='png')
  urlbox_apikey = 'YOUR_API_KEY'
  urlbox_secret = 'YOUR_API_SECRET'
  query = {
    :url         => url, # required - the url you want to screenshot
    :force       => options[:force], # optional - boolean - whether you want to generate a new screenshot rather than receive a previously cached one - this also overwrites the previously cached image
    :full_page   => options[:full_page], # optional - boolean - return a screenshot of the full screen
    :thumb_width => options[:thumb_width], # optional - number - thumbnail the resulting screenshot using this width in pixels
    :width       => options[:width], # optional - number - set viewport width to use (in pixels)
    :height      => options[:height], # optional - number - set viewport height to use (in pixels)
    :quality     => options[:quality] # optional - number (0-100) - set quality of the screenshot
  query_string = query.
    sort_by {|s| s[0].to_s }.
    select {|s| s[1] }.       
    map {|s| {|v| encodeURIComponent(v.to_s) }.join('=') }.
  token = OpenSSL::HMAC.hexdigest('sha1', urlbox_secret, query_string)

### USAGE: (format can be png or jpg, we default to png) ###
url = urlbox("", {thumb_width: 200, full_page: true, quality: 90}, 'jpg')
puts url
# url: ""


Sample code to take website screenshots in PHP

Check out our composer package here, and on github

// run this on the command line to install the urlbox php package:
// composer require urlbox/screenshots

use Urlbox\Screenshots\Urlbox;

$urlbox = Urlbox::fromCredentials('API_KEY', 'API_SECRET');

// only required option is a url:
$options['url'] = '';

// specify any other options to augment the screenshot...
$options['width'] = 320;

// Create the Urlbox URL
$urlboxUrl = $urlbox->generateUrl($options);

// $urlboxUrl is now ''

// Generate a screenshot by loading the Urlbox URL in an img tag:
echo '<img src="'.$urlboxUrl.'" alt="Test screenshot generated by Urlbox">'


Sample code to take website screenshots in Python

#pypy package coming soon
import hmac
from hashlib import sha1
    from urllib import urlencode
except ImportError:
    from urllib.parse import urlencode
def urlbox(args):
    apiKey = "xxx-xxx"
    apiSecret = "xxx-xxx"
    queryString = urlencode(args, True)
    hmacToken =, str.encode(queryString), sha1)
    token = hmacToken.hexdigest().rstrip('
    return "" % (apiKey, token, queryString)

argsDict = {'url' : "", 'thumb_width': 400}
print(urlbox (argsDict))


Sample code to take website screenshots in Java

import java.math.BigInteger;
import java.util.Map;
import java.util.HashMap;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class Urlbox { 

  private String key;
  private String secret;

  Urlbox(String api_key, String api_secret) {
    this.key = api_key;
    this.secret = api_secret;

  // main method demos Example Usage
  public static void main(String[] args) { 
    String urlboxKey = "your-urlbox-api-key";
    String urlboxSecret = "your-urlbox-secret";

    // Set request options
    Map<String, Object> options = new HashMap<String, Object>();
    options.put("width", 1280);
    options.put("height", 1024);
    options.put("thumb_width", 240);
    options.put("full_page", "false");
    options.put("force", "false");

    // Create urlbox object with api key and secret
    Urlbox urlbox = new Urlbox(urlboxKey, urlboxSecret);
    try {
      // Call generateUrl function of urlbox object
      String urlboxUrl = urlbox.generateUrl("", options);
      // Now do something with urlboxUrl.. put in img tag, etc..
    } catch (UnsupportedEncodingException ex) {
      throw new RuntimeException("Problem with url encoding", ex);

  public String generateUrl(String url, Map<String,Object> options) throws UnsupportedEncodingException {

    String encodedUrl = URLEncoder.encode(url, "UTF-8");
    String queryString = String.format("url=%s", encodedUrl);

    for (Map.Entry<String, Object> entry : options.entrySet()) {
      String queryParam = "&"+entry.getKey()+"="+entry.getValue(); 
      queryString += queryParam;

    String token = generateToken(queryString, this.secret);
    String result = String.format("", this.key, token, queryString);
    return result;
  private String generateToken(String input, String key) {
    String lSignature = "None";
    try {
      Mac lMac = Mac.getInstance("HmacSHA1");
      SecretKeySpec lSecret = new SecretKeySpec(key.getBytes(), "HmacSHA1");

      byte[] lDigest = lMac.doFinal(input.getBytes());
      BigInteger lHash = new BigInteger(1, lDigest);
      lSignature = lHash.toString(16);
      if ((lSignature.length() % 2) != 0) {
        lSignature = "0" + lSignature;
    } catch (NoSuchAlgorithmException lEx) {
      throw new RuntimeException("Problems calculating HMAC", lEx);
    } catch (InvalidKeyException lEx) {
      throw new RuntimeException("Problems calculating HMAC", lEx);
    return lSignature;


Sample code to take website screenshots in C#

Check out our nuget package here

using UrlboxMain;

namespace Screenshot
  public class Screenshotter
    Urlbox urlbox = new Urlbox("YOUR_URLBOX_API_KEY", "YOUR_URLBOX_API_SECRET");

    public void GetScreenshotUrl()
      dynamic options = new ExpandoObject();
      options.Width = 1280;
      options.Thumb_Width = 500;
      options.Full_Page = true;

      var output = urlbox.GenerateUrl("", options);
      // output is now
      // to generate a screenshot image you would make a simple GET request to this URL, for example putting it inside an <img> tag.
 // ================================================================
// UrlboxMain project/package:
using System;
using System.Collections.Generic;
using System.Dynamic;
using System.Linq;
using System.Text;
using PCLCrypto;

namespace UrlboxMain
  public class Urlbox
    String apiKey;
    String apiSecret;
    static List<String> encodedPropertyNames = new List<String> { "user_agent", "bg_color", "hide_selector", "click_selector", "highlight", "highlightbg", "highlightfg" };
    static List<String> booleanPropertyNames = new List<String> { "force", "retina", "full_page", "disable_js" };

    public Urlbox(String apiKey, String apiSecret)
      if (String.IsNullOrEmpty(apiKey) || String.IsNullOrEmpty(apiSecret))
        throw new ArgumentException("Please provide your API Key and API Secret");
      this.apiKey = apiKey;
      this.apiSecret = apiSecret;

    public string GenerateUrl(string url)
      return this.GenerateUrl(url, new ExpandoObject());

    public string GenerateUrl(string url, ExpandoObject options)
      if (String.IsNullOrEmpty(url))
        throw new ArgumentException("Please provide a url in order to generate a screenshot URL");
      var encodedUrl = urlEncode(url);
      var format = "png";

      byte[] key = Encoding.UTF8.GetBytes(this.apiSecret);
      var urlString = string.Format("url={0}", encodedUrl);
      StringBuilder sb = new StringBuilder(urlString);

      foreach (KeyValuePair<string, object> kvp in options)
        var optionName = kvp.Key.ToLower();
        var optionValue = kvp.Value.ToString();
        if (String.IsNullOrEmpty(optionValue))
        if (string.Equals(optionName, "format")){
          format = optionValue;
        if (encodedPropertyNames.Contains(optionName))
          optionValue = urlEncode(optionValue);
        if (booleanPropertyNames.Contains(optionName))
          if (!(bool)kvp.Value) { continue; }
          optionValue = optionValue.ToLower();
        sb.Append(string.Format("&{0}={1}", optionName, optionValue));

      var queryString = sb.ToString();
      var uniqueToken = generateToken(queryString, key);
      return string.Format("{0}/{1}/{2}?{3}", this.apiKey, uniqueToken, format, queryString);

    private static string generateToken(String data, byte[] key)
      var algorithm = WinRTCrypto.MacAlgorithmProvider.OpenAlgorithm(MacAlgorithm.HmacSha1);
      CryptographicHash hasher = algorithm.CreateHash(key);
      byte[] mac = hasher.GetValueAndReset();
      var macStr = byteArrayToString(mac);
      return macStr;

    private static string byteArrayToString(byte[] ba)
      string hex = BitConverter.ToString(ba).ToLower();
      return hex.Replace("-", "");

    private static string urlEncode(string url)
      // make it behave like javascript encodeURIComponent()
      var encoded = Uri.EscapeDataString(url);
      encoded = encoded.Replace("%28", "(");
      encoded = encoded.Replace("%29", ")");
      return encoded;