We use cookies to enhance user experience, analyze site usage, and assist in our marketing efforts. By continuing to browse or closing this banner, you acknowledge that you have read and agree to our Cookie Policy, Privacy Policy and Terms of Service.

Browserstack logo
  • Live for Teams
  • Pricing
    • Test your websites
    • Live
      Interactive cross browser testing
    • Automate
      Selenium testing at scale
    • Percy
      Visual testing & review
    • Test your mobile apps
    • App Live
      Interactive native & hybrid app testing
    • App Automate
      Test automation for native & hybrid mobile apps
    • App Percy Beta
      Visual testing for native & hybrid mobile apps

    Use BrowserStack with your favourite products. See our Integrations ⟶

    • For Teams
    • Enterprise
    • Tools
    • Screenshots
    • Responsive
    • SpeedLab
    • Documentation
    • Support
    • Status
    • Release Notes
    • Open Source
    • Events
    • Champions
  • Live for Teams
  • Pricing
  • Sign in
  • Free Trial
  • Test your websites
  • Live
    Interactive cross browser testing
  • Automate
    Selenium testing at scale
  • Percy
    Visual testing & review
  • Test your mobile apps
  • App Live
    Interactive native & hybrid app testing
  • App Automate
    Test automation for native & hybrid mobile apps
  • App Percy
    Visual testing for native & hybrid mobile apps
  • For Teams
  • Enterprise
  • Tools
  • Screenshots
  • Responsive
  • SpeedLab
  • Documentation
  • Support
  • Status
  • Release Notes
  • Open Source
  • Events
  • Champions
  • Get help
  • Documentation
  • Developer tools
  • Integrations
  • Integration URL
  • Local testing
  • References
  • Features
  • Mobile Features
  • Test on Right Devices
  • Browsers & Devices
  • Security
  • Status
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"
    }
   ]
}

In This Article

  • Language Bindings
  • 3rd party tools
  • Authentication
  • Get list of available OS and browsers
  • Generate screenshots for a URL
  • Generate the list of screenshots and their states

Related Articles

Browsers & Platforms

Products

  • Live
  • Automate
  • Percy
  • App Live
  • App Automate
  • App Percy Beta
  • Screenshots
  • Responsive
  • Enterprise
  • SpeedLab New!

Platform

  • Browsers & Devices
  • Data Centers
  • Device Features
  • Security

Solutions

  • Test on iPhone
  • Test on iPad
  • Test on Galaxy
  • Test In IE
  • Android Testing
  • iOS Testing
  • Cross Browser Testing
  • Emulators & Simulators
  • Selenium
  • Cypress
  • Android Emulators
  • Visual Testing

Resources

  • Test on Right Devices
  • Support
  • Status
  • Release Notes
  • Case Studies
  • Blog
  • Events
  • Test UniversityBeta
  • Champions
  • Mobile Emulators
  • Guide
  • Responsive Design
  • Nightwatch

Company

  • About Us
  • Customers
  • Careers We're hiring!
  • Open Source
  • Partners
  • Press
BrowserStack Logo An illustrated of BrowserStack Logo

Social

  • BrowserStack Twitter Account An illustrated of white twitter Logo
  • BrowserStack FaceBook Account An illustrated of white FaceBook Logo
  • BrowserStack LinkedIn Account An illustrated of white LinkedIn Logo
  • BrowserStack Youtube Channel An illustrated of white youtube Logo
  • BrowserStack Instagram Account An illustrated of white instagram Logo
BrowserStack Contact Us Icon An illustration of white contact us icon Contact Us

© 2011-2023 BrowserStack - The Most Reliable Mobile App & Cross Browser Testing Company

  • Terms of Service
  • Privacy Policy
  • Cookie Policy
  • Sitemap