Quick Start

Generating screenshots just requires a single request to the Screenshot Bin API. Here's what it looks like with some popular programming languages:

curl https://api.screenshotbin.com/v1/screenshot \
  -u REPLACE_WITH_SECRET_API_KEY: \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.example.com"}'

The code snippets above should be enough to get started, but read on for more in-depth documentation!

How It Works

When you request a screenshot, it'll be immediately handled by a server in our cloud cluster. This server will navigate a headless browser to the specified url, snap a screenshot, and perform any requested post-processing such as image resizing. We'll then return a publicly accessible image url to you.

Images generated by Screenshot Bin will be cached for a configurable amount of time (up to 30 days). Subsequent requsts for the same url and options will immediately return the cached url, and will not count towards your plan.

API Overview

Our API is a standard REST-ful API that can be accessed using off-the-shelf HTTP clients in any popular programming language. We use built-in HTTP features, like HTTP authentication and status codes, and JSON is returned by all API responses, including errors.

Authentication

Authenticate your account when using the API by including your secret API key in the request. You can create new API keys on the Account page. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your secret API key as the basic auth username value. You do not need to provide a password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Speed & Accuracy

Our service is highly optimized for speed, but we can only be as fast as the website you are capturing. If a website has large, slow-loading images, we wait for those images to load by default so your screenshot is accurate.

Luckily, you as a developer have control over this trade-off between speed and accuracy. API options like waitUntilEvent, waitUntilSelector, and delay can ensure that all resources have loaded, but may also increase your request time. We encourage you to explore these options and optimize for your use case.

API Reference

POST /v1/screenshot

Arguments
url
String
required
URL of the page to screenshot. Should start with http:// or https://
Example: 'https://www.google.com'
format
String
optional
Image file format. Supported types are png or jpeg.
Defaults to png
imgWidth
Number
optional
Width in pixels of the final image, useful for creating thumbnails. The image height will be determined automatically based on aspect ratio of the original screenshot, which is configurable through viewportWidth and viewportHeight.
Defaults to same as viewportWidth
viewportWidth
Number
optional
Width in pixels of the viewport when taking the screenshot. Using lower values like 460 can help emulate what the page looks like on mobile devices.
Defaults to 1440
viewportHeight
Number
optional
Height in pixels of the viewport when taking the screenshot.
Defaults to 900
deviceScaleFactor
Number
optional
Sets device scale factor (basically dpr) to emulate high-res/retina displays. Number from 1 to 4.
Defaults to 1
delay
Number
optional
If set, we'll wait for the specified number of milliseconds after the page load event before taking a screenshot.
waitUntilEvent
String
optional
Controls when the screenshot is taken as the page loads. Supported events include:
  • load - window load event fired (default)
  • domcontentloaded - DOMContentLoaded event fired.
  • networkidle0 - wait until there are zero network connections for at least 500ms.
  • networkidle2 - wait until there are no more than 2 network connections for at least 500ms.
domcontentloaded is the fastest but riskiest option–many images and other asynchronous resources may not have loaded yet. networkidle0 is the safest but slowest option. load is a nice middle ground.
Defaults to load.
waitUntilSelector
String
optional
If set, we'll wait for the element specified by this selector to become present before taking a screenshot.
Example: '.ready-for-screenshot'
userAgent
String
optional
Overrides the user agent string that the browser sends during a web request.
Defaults to Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.94 Safari/537.36
full
Boolean
optional
If set to true, we will capture the full height of the page after it has rendered, rather than just the viewport height.
Defaults to false
lazyLoad
Boolean
optional
When full is enabled, we will attempt to lazy load all images on the page before capturing a screenshot. Set this to false if you don't care about lazy loading and you'll see a minor speed increase.
Defaults to true when full is enabled.
transparency
Boolean
optional
Hides default white webpage background for capturing screenshots with transparency, only works when format is png
Defaults to false
timeout
Number
optional
The number of milliseconds to wait for a page load event before taking a screenshot or failing (controlled by failOnTimeout)
Defaults to 10000 (10 seconds)
failOnTimeout
Boolean
optional
If set to false, we will take a screenshot when timeout is reached instead of failing the request.
Defaults to false
ttl
Number
optional
Number of seconds to cache the screenshot for. Subsequent requsts for the same url and options will immediately return the cached url, and will not count towards your plan.
Defaults to 2592000 (30 days)
fresh
Boolean
optional
Ignore any existing cached images and force a fresh screenshot to be taken.
Defaults to false

Successful reqests will return 200 with the following response format:

{
  "url": "https://i.screenshotbin.com/i/49e6a2bfeee24ed4816f527ad0eb35e9.png",
  "created": 1511587137, // Seconds from unix epoch when image was generated
  "expires": 1514179135, // Seconds from unix epoch when image will expire
  "fromCache": true,     // true if screenshot was loaded from cache
  "monthlyQuota": {      // Information about your monthly plan
    "plan": "Free",
    "requestsAllowed": 100,
    "requestsUsed": 1,
    "requestsRemaining": 99
  }
}

Failed reqests will return 4XX or 5XX with the following response format:

{
  "status": "error",
  "message": "Screenshot failed due to timeout, page did not load before 10000 milliseconds."
}