BrowserStack Screenshot API: Capture a URL at a Specific Viewport

BrowserStack’s Screenshots API documents desktop resolution presets, not arbitrary viewport width and height parameters. The API reference lists win_res and mac_res choices. If you need an exact custom browser-window size, BrowserStack documents a separate workflow: resize an Automate browser window before taking a Percy screenshot. That Percy workflow is not a Screenshots API parameter. BrowserStack’s Screenshots API reference labels itself API Version 1.0 and does not show a publication or revision date, so confirm current endpoint behavior and plan eligibility in your account before relying on it.

What “specific viewport” means in the Screenshots API

The documented desktop controls are operating-system-specific presets. The reference lists these values:

Operating system	Parameter	Documented resolutions
Windows	`win_res`	`1024x768`, `1280x1024`
Mac	`mac_res`	`1024x768`, `1280x960`, `1280x1024`, `1600x1200`, `1920x1080`

Those are the choices shown in the cited API documentation. It does not document a general width plus height pair or say that arbitrary values are accepted. Do not assume that sending an unlisted resolution works.

Mobile device selection is documented separately through device. For mobile captures, orientation is also available; the documented default is portrait. These settings do not turn the desktop preset parameters into arbitrary viewport controls.

Submit a screenshot job

The documented flow is to authenticate with your BrowserStack username and access key using HTTP Basic authentication, submit a POST /screenshots request with the URL and browser/OS configuration, then retrieve the job result. The API reference documents inputs including os, os_version, browser, browser_version, and, for mobile, device.

The reference excerpt does not provide a base URL or a complete copy-paste request with all required values. To avoid guessing the API host or required fields, set BROWSERSTACK_SCREENSHOTS_ENDPOINT to the current Screenshots API submission endpoint shown in your official account documentation. The examples below send the documented POST /screenshots request shape to that configured endpoint. Use values valid for your account and the current API documentation.

cURL

export BROWSERSTACK_USERNAME="YOUR_USERNAME"
export BROWSERSTACK_ACCESS_KEY="YOUR_ACCESS_KEY"
export BROWSERSTACK_SCREENSHOTS_ENDPOINT="YOUR_DOCUMENTED_POST_SCREENSHOTS_ENDPOINT"

curl --fail-with-body --user "$BROWSERSTACK_USERNAME:$BROWSERSTACK_ACCESS_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com",
    "os": "Windows",
    "os_version": "YOUR_SUPPORTED_OS_VERSION",
    "browser": "YOUR_SUPPORTED_BROWSER",
    "browser_version": "YOUR_SUPPORTED_BROWSER_VERSION",
    "win_res": "1280x1024",
    "quality": "Original",
    "wait_time": 5
  }' \
  "$BROWSERSTACK_SCREENSHOTS_ENDPOINT"

Replace the OS and browser values with combinations supported by your account. To use a Mac preset, use the documented mac_res parameter and one of its listed values instead of win_res. The request returns a job identifier or job information; use the returned identifier in the retrieval step below.

Python

import os
import requests

endpoint = os.environ["BROWSERSTACK_SCREENSHOTS_ENDPOINT"]
auth = (
    os.environ["BROWSERSTACK_USERNAME"],
    os.environ["BROWSERSTACK_ACCESS_KEY"],
)
payload = {
    "url": "https://example.com",
    "os": "Windows",
    "os_version": "YOUR_SUPPORTED_OS_VERSION",
    "browser": "YOUR_SUPPORTED_BROWSER",
    "browser_version": "YOUR_SUPPORTED_BROWSER_VERSION",
    "win_res": "1280x1024",
    "quality": "Original",
    "wait_time": 5,
}

response = requests.post(endpoint, json=payload, auth=auth, timeout=60)
response.raise_for_status()
print(response.json())

Node.js

const endpoint = process.env.BROWSERSTACK_SCREENSHOTS_ENDPOINT;
const username = process.env.BROWSERSTACK_USERNAME;
const accessKey = process.env.BROWSERSTACK_ACCESS_KEY;

if (!endpoint || !username || !accessKey) {
  throw new Error('Set the BrowserStack endpoint, username, and access key.');
}

const payload = {
  url: 'https://example.com',
  os: 'Windows',
  os_version: 'YOUR_SUPPORTED_OS_VERSION',
  browser: 'YOUR_SUPPORTED_BROWSER',
  browser_version: 'YOUR_SUPPORTED_BROWSER_VERSION',
  win_res: '1280x1024',
  quality: 'Original',
  wait_time: 5,
};

const response = await fetch(endpoint, {
  method: 'POST',
  headers: {
    Authorization: `Basic ${Buffer.from(`${username}:${accessKey}`).toString('base64')}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(payload),
});

if (!response.ok) {
  throw new Error(`Screenshot submission failed: ${response.status} ${await response.text()}`);
}
console.log(await response.json());

Choose the documented resolution and other options

Pick the preset that matches the screen size you want to inspect, and pair it with a valid browser and OS configuration. The names and combinations accepted for browser, OS, and version depend on the API’s supported configurations; consult the current reference rather than treating the placeholders above as literal values.

Option	What the reference documents	Practical use
`win_res`	Windows resolution presets: 1024×768 or 1280×1024	Desktop capture on a Windows configuration
`mac_res`	Mac presets: 1024×768, 1280×960, 1280×1024, 1600×1200, or 1920×1080	Desktop capture on a Mac configuration
`device`	Mobile device selection	Capture a documented mobile device configuration
`orientation`	Mobile orientation; portrait is the stated default	Request a landscape mobile capture when needed
`quality`	`Original` or `Compressed`; Compressed is the stated default	Choose the output quality behavior documented by the API
`local`	For pages reached through a configured Local Testing connection	Capture a site accessible through that connection
`wait_time`	2, 5, 10, 15, 20, or 60 seconds; default is 5	Allow a page more time before capture
`callback_url`	Callback notification after processing	Receive a POST when the job is processed

Only use documented values and fields. The reference does not establish arbitrary viewport dimensions, current processing-time guarantees, or present-day account pricing.

Retrieve the result

The API reference documents retrieving a job with GET /screenshots/<JOB-ID>.json. The response example includes job state and screenshot records with browser or device metadata and image and thumbnail URLs. Treat that response as an example of the documented shape, not a timing guarantee.

curl --fail-with-body --user "$BROWSERSTACK_USERNAME:$BROWSERSTACK_ACCESS_KEY" \
  "YOUR_DOCUMENTED_API_BASE/screenshots/YOUR_JOB_ID.json"

For an event-driven workflow, supply callback_url when submitting the job. BrowserStack documents that it sends a POST after processing. Your callback handler should validate the request according to the current BrowserStack guidance, record the job identifier and state, and handle duplicate notifications safely.

When exact custom dimensions are required

BrowserStack’s Percy-on-Automate documentation describes a different route: resize the Automate browser window using Automate’s window-resizing APIs, then call percyScreenshot. That is a Percy and Automate workflow, not a Screenshots API setting. Follow the official Percy viewport-width guide for its code and prerequisites.

Use the Screenshots API when one of its documented OS resolution presets or mobile configurations meets the need. Consider the Automate and Percy route when the required width and height are not among those presets and your workflow is already based on Percy. The available documentation here does not support a broader claim about arbitrary dimensions in other BrowserStack products.

Access and plan eligibility

The Screenshots API reference says it is available in Automate plans that include browsers; Live-only subscribers can use Screenshots through the webpage. The reference does not establish current plan names, prices, or contract terms. Check your account’s current plan and documentation before building a production dependency on the endpoint.

Or skip the browser setup

ScreenshotNeo offers a website screenshot API and MCP server. Make one GET request to capture a URL; see the API documentation for the request options.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://example.com \
  -o shot.webp

ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for 1,000 free screenshots a month, with no card.

Troubleshooting

Symptom	Likely cause	What to do
HTTP 401 Unauthorized	The reference identifies 401 as the unauthorized response; credentials may be missing or incorrect.	Check the username and access key, ensure the request uses HTTP Basic authentication, and confirm the account has access.
The requested resolution is rejected or ignored	The value may not be one of the documented presets, or the OS-specific parameter may not match the selected OS.	Use a listed `win_res` or `mac_res` value with its corresponding OS configuration. The reference does not promise arbitrary dimensions.
Mobile capture has the wrong orientation	The documented default is portrait.	Set the documented `orientation` value for the intended mobile orientation.
The page is captured before it is ready	The default wait is documented as 5 seconds, which may not suit the page.	Try a documented `wait_time` value appropriate to the page. The listed choices are 2, 5, 10, 15, 20, or 60 seconds.
Local page cannot be reached	The `local` option is for pages reached through a configured Local Testing connection.	Confirm Local Testing is configured and the request uses the documented local setting.
Job result is not immediately available	Submission and result retrieval are separate steps.	Retrieve the job using its ID, or configure `callback_url` and process the documented callback. The reference does not promise a specific processing time.
API endpoint or request fields are unclear	The cited page may have changed, and its version-labeled reference is undated.	Use the current official API documentation and account details to confirm the endpoint, required fields, supported configurations, and plan eligibility before deployment.

Performance, reliability, and cost considerations

Wait time: A longer documented wait can allow more page content to render, but it also means a job may take longer. The API material does not provide a processing-time benchmark or service-level guarantee.
Quality: The documented choices are Original and Compressed, with Compressed as the stated default. Choose based on your image-size and fidelity needs; the reference does not quantify file sizes.
Asynchronous handling: Treat submission and retrieval as separate operations. For automation, use the callback option and make the receiver tolerant of repeated notifications and delayed job completion.
Plan and spend: The API reference ties access to Automate plans that include browsers, but it does not establish current prices or plan names. Verify current account terms before estimating cost.
Configuration coverage: If you need repeatable comparisons, record the OS, OS version, browser, browser version, resolution or device, orientation, quality, and wait time with each result.

FAQ

Can I pass width=1440 and height=900 to the Screenshots API?

The cited API reference does not document arbitrary width and height parameters. It documents OS-specific desktop resolution presets.

Does the Screenshots API use the same viewport controls as Percy?

No such equivalence is established by the documentation. The Percy guide describes resizing an Automate browser window before taking a Percy screenshot, a separate workflow.

Can Live-only subscribers call the API?

The cited reference says the API is available in Automate plans that include browsers, while Live-only subscribers can use Screenshots through the webpage. Confirm current eligibility in your account.

Does the Bug Capture screenshot limitation apply to all BrowserStack captures?

No. The FAQ about viewport-only capture is specifically for BrowserStack Bug Capture and should not be generalized to the Screenshots API or other products.

Sources

BrowserStack Screenshots API documentation (API Version 1.0; undated reference).
BrowserStack Percy guide: capture screenshots at different viewport widths in Percy on Automate.
BrowserStack Bug Capture Screenshots FAQ (product-specific limitation).