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
      Manual cross-browser testing
    • Automate
      Browser automation grid
    • Percy
      Visual testing & review
    • Accessibility Testing
      Super app to find & report issues
    • Test your mobile apps
    • App Live
      Manual real device testing
    • App Automate
      Real device automation grid
    • App Percy
      Visual testing for mobile apps
    • Test management & optimization
    • Test Management
      Unify & track all test cases
    • Test Observability
      Smart test reporting & debugging
    • Test development
    • Nightwatch.js
      End-to-End testing framework

    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
    Manual cross-browser testing
  • Automate
    Browser automation grid
  • Percy
    Visual testing & review
  • Accessibility Testing
    Super app to find & report issues
  • Test your mobile apps
  • App Live
    Manual real device testing
  • App Automate
    Real device automation grid
  • App Percy
    Visual testing for mobile apps
  • Test management & optimization
  • Test Management
    Unify & track all test cases
  • Test Observability
    Smart test reporting & debugging
  • Test development
  • Nightwatch.js
    End-to-End testing framework
  • 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 New
    • Test Management Beta
    • Test Observability Beta
    • Accessibility Testing Beta
    • Nightwatch
    • Enterprise

    Tools

    • SpeedLab
    • Screenshots
    • Responsive

    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

    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

    © 2023 BrowserStack. All rights reserved.

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