Home Support Screenshots API

Screenshots API

The Screenshots API allows headless creation of screenshots for a URL. The API allows selection of OS and browsers, starting and stopping screenshot generation.

Note: Screenshots API is only available in Automate plans that include browsers. If you are subscribed only to Live plans, you can use Screenshots through webpage.

Language bindings

Language binding Description
Ruby
API Version: 1.0		 A ruby gem for working with the BrowserStack Screenshots API

3rd party tools

Tools Description
ScreenShooter
Developed by: Ben Lopatin		 A tool for generating BrowserStack screenshots from the command-line interface.
pybrowserstack-screenshots
Developed by: Clark Mckenzie		 python api wrapper and client for Browserstack Screenshots API including PhantomCSS support. Starts screenshot jobs at Browserstack and downloads the screenshots when they are complete. Tests for visual regressions using PhantomCSS.
browserstack
Developed by: Scott Gonzalez		 A node.js JavaScript client for working with BrowserStack through its REST API and Screenshots API.

Authentication

All methods need to authenticate who you are before running any process. Authentication is done using your username and BrowserStack access key within the HTTP request. For example:

$ curl -u "USERNAME:ACCESS_KEY" https://www.browserstack.com/screenshots

Warning: A 401 Unauthorized response is given if an unauthorized request is made.

Get list of available OS and browsers

Usage 
GET /screenshots/browsers.json
Example 
curl -u "USERNAME:ACCESS_KEY" -H "Content-Type: application/json" -H "Accept: application/json"  -d '{"browsers": [{"os": "Windows", "os_version": "7", "browser_version": "8.0", "browser": "ie"}], "url": "http://google.com"}' https://www.browserstack.com/screenshots
Response 
[
  {
    "os": "Windows",
    "os_version": "XP",
    "browser": "chrome"
    "browser_version": "21.0"
    "device": null
  }
  {
    "os": "ios",
    "os_version": "6.0",
    "browser": "Mobile Safari"
    "browser_version": null
    "device": "iPhone 4S (6.0)"
  }
  ....
]

Generate screenshots for a URL

Parameters Value
url
The URL of the desired page.		 Example: www.example.com
os
OS you want to test.		 Windows, OS X, ios, android
Example: Windows
os_version
The OS version you want to test.		 Example: 8.1
browser
The browser you want to test.		 ie, chrome, firefox, safari, opera, Android Browser
Example: chrome
browser_version
The browser version you want to test.		 Example: 31.0
device
Required if you want to test on a mobile device.		 Example: iPhone 4S
orientation
Required if specifying the screen orientation for the device.		 portrait, landscape
Default: portrait
mac_res
Required if specifying the screen resolution for browsers on OSX.		 Default: 1024x768
Values: 1024x768, 1280x960, 1280x1024, 1600x1200, 1920x1080
win_res
Required if specifying the screen resolution for browsers on Windows.		 Default: 1024x768
Values: 1024x768, 1280x1024
quality
Required if specifying the quality of the screenshot.		 Default: Compressed
Values: Original, Compressed
local
Required if the page is local and that a Local Testing connection has been set up.		 Default: false
Values: true, false
wait_time
Required if specifying the time (in seconds) to wait before taking the screenshot.		 Default: 5
Values: 2, 5, 10, 15, 20, 60
callback_url Default: nil
Required if results are to be sent back to a public URL

Note: If specified, the data will be posted to callback_url , which must be a valid URL. The response contains a listing of all screenshots generated once processing has completed. Alternatively, the response is accessible using GET /screenshots/<JOB-ID>.json.

Usage 
POST /screenshots

{
  "url":"www.google.com",
  "callback_url": "http://staging.example.com",
  "win_res": "1024x768",
  "mac_res": "1920x1080",
  "quality": "compressed",
  "wait_time": 5,
  "orientation": "portrait",
  "browsers":[
   {
     "os":"Windows",
     "os_version":"XP",
     "browser":"ie",
     "browser_version":"7.0"
   },
   {
     "os":"ios",
     "os_version":"6.0",
     "device":"iPhone 4S (6.0)"
    },
    ....
  ],
}
Response 
{
  "job_id":"13b93a14db22872fcb5fd1c86b730a51197db319",
  "callback_url": "http://staging.example.com",
  "win_res": "1024x768",
  "mac_res": "1920x1080",
  "quality": "compressed",
  "wait_time": 5,
  "orientation": "portrait",
  "screenshots": [
   {
     "os":"Windows",
     "os_version":"XP",
     "browser":"ie",
     "id":"be9989892cbba9b9edc2c95f403050aa4996ac6a",
     "state":"pending",
     "browser_version":"7.0",
     "url":"www.google.com"
   },
   {
     "os":"ios",
     "os_version":"6.0",
     "id":"1f3a6054e09592e239e9ea79c247b077e68d3d71",
     "state":"pending",
     "device":"iPhone 4S (6.0)",
     "url":"www.google.com"
   }
  ....
  ]
}

Generate the list of screenshots and their states

Usage 
GET /screenshots/<JOB-ID>.json
Response 
{
  "id":"13b93a14db22872fcb5fd1c86b730a51197db319",
  "state":"done",
  "callback_url": "http://staging.example.com",
  "win_res": "1024x768",
  "mac_res": "1920x1080",
  "quality": "compressed",
  "wait_time": 5,
  "screenshots": [
    {
      "os":"Windows",
      "os_version":"XP",
      "browser":"ie",
      "browser_version":"7.0",
      "id":"be9989892cbba9b9edc2c95f403050aa4996ac6a",
      "state":"done",
      "url":"www.google.com",
      "thumb_url":"https://www.browserstack.com/screenshots/13b93a14db22872fcb5fd1c86b730a51197db319/thumb_winxp_ie_7.0.jpg",
      "image_url":"https://www.browserstack.com/screenshots/13b93a14db22872fcb5fd1c86b730a51197db319/winxp_ie_7.0.png",
      "created_at":"2013-03-14 16:25:45 UTC"
    },
    {
      "os":"Windows",
      "os_version":"7",
      "browser":"ie",
      "browser_version":"8.0",
      "id":"1f3a6054e09592e239e9ea79c247b077e68d3d71",
      "state":"done",
      "url":"www.google.com",
      "thumb_url":"https://www.browserstack.com/screenshots/13b93a14db22872fcb5fd1c86b730a51197db319/thumb_win7_ie_8.0.jpg",
      "image_url":"https://www.browserstack.com/screenshots/13b93a14db22872fcb5fd1c86b730a51197db319/win7_ie_8.0.png",
      "created_at":"2013-03-14 16:25:45 UTC"
    }
   ]
}