Browserstack logo Search logo Open Menu Close Menu
  • Products
  • Developers
  • Live for Teams
  • Pricing
  • Products
      • Test your websites
      • Live
        Interactive cross browser testing
      • Automate
        Selenium testing at scale
      • Percy New
        Visual testing & review
      • Test your mobile apps
      • App Live
        Interactive native & hybrid app testing
      • App Automate
        Test automation for native & hybrid mobile apps

      Use BrowserStack with your favourite products. See our Integrations ⟶

      • For Teams
      • Enterprise
      • Tools
      • Screenshots
      • Responsive
      • SpeedLab
  • Developers
    • Documentation
    • Support
    • Status
    • Release Notes
    • Open Source
    • Events
  • Live for Teams
  • Pricing
  • Sign in
  • Free Trial
  • Products
  • 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
  • For Teams
  • Enterprise
  • Tools
  • Screenshots
  • Responsive
  • SpeedLab
  • Developers
  • Documentation
  • Support
  • Status
  • Release Notes
  • Open Source
  • Events
  • 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.

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 New!
  • App Live
  • App Automate
  • Screenshots
  • Responsive
  • Enterprise
  • SpeedLab New!
Platform
  • Browsers & Devices
  • Data Centers
  • Mobile Features
  • Security
Resources
  • Test on Right Devices
  • Support
  • Status
  • Release Notes
  • Case Studies
  • Blog
  • Events
Company
  • About Us
  • Customers
  • Careers We're hiring!
  • Open Source
  • Partners
  • Press
  • Contact
Social
Browserstack logo
Do more with BrowserStack
  • Test In IE
  • Mobile Emulators
  • Test on iPhone
  • Test on iPad
  • Test on Galaxy
  • Android Testing
  • iOS Testing
  • Guide
  • Cross Browser Testing
  • Emulators & Simulators
  • Selenium
  • Cypress
  • Android Emulators
  • Responsive Design
  • Visual Testing

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

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

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.