BrowserStack Screenshot API Times Out on Large Web Pages

BrowserStack’s Screenshots service documents a two-minute processing limit for each screenshot. If it is not generated within that limit, the result is marked “Timed Out.” The documentation does not establish that page size alone causes a timeout, and the reviewed sources do not document a setting that raises the limit. BrowserStack’s Screenshots API documentation describes submitting a job and then retrieving its result by job ID or receiving it at a callback URL.

That distinction matters: a large page may be part of the circumstances, but the timeout by itself does not identify the cause. First confirm which BrowserStack product produced the error, then inspect the job state and use evidence from the failing URL and capture configuration to narrow down what happened.

1. Confirm the product and exact error

BrowserStack has separate products and workflows that involve screenshots. The Screenshots API’s per-screenshot “Timed Out” result is different from timeouts in an Automate Selenium session or full-page capture behavior in Percy.

Workflow	What the documentation says	What not to assume
Screenshots API	A screenshot has a two-minute processing limit; a screenshot not generated within it receives “Timed Out.” The API supports checking a job endpoint or receiving results through a callback.	The reviewed documentation does not identify page height, page weight, or another page property as the cause, or document a way to raise this cap. Screenshots API
Automate Selenium session	BrowserStack documents a 90-second idle timeout and a 240-second socket timeout for an unresponsive browser in Automate sessions.	Those session timeouts are not the Screenshots API’s per-screenshot processing limit. Automate timeouts
Percy full-page screenshot	Percy has separate guidance for page readiness, lazy loading, dynamic elements, and full-page dimensions.	Percy guidance and limits do not establish a Screenshots API limit or workaround. Percy full-page screenshots

Before changing code, record the product name, exact error label, job or session ID, URL, requested browsers or devices, and timestamp. If an error is from Automate or Percy, follow that product’s documentation rather than treating it as a Screenshots API timeout.

2. Inspect the Screenshots API job

The API uses an asynchronous job workflow. A client receiving the initial submission response has not necessarily received the final screenshots. Check the job state and results with the documented job endpoint, or configure a callback URL to receive the results when processing completes.

1. Submit the screenshot request using the parameters and authentication shown in your BrowserStack account’s API documentation.
2. Save the returned job ID and the full submission response.
3. Check GET /screenshots/<JOB-ID>.json for the job’s state and screenshot results, or inspect the callback delivery if you supplied callback_url.
4. Classify the outcome: still pending, completed, failed, or marked “Timed Out.” This separates a job-level outcome from a client that stopped waiting for a response.
5. If it repeatedly times out, send BrowserStack Support the job ID, URL, requested browsers/devices, timestamp, and exact error. The reviewed documentation does not say which page characteristic caused a given timeout.

BrowserStack documents wait_time as the delay before taking a screenshot. It is not documented as an extension to the two-minute processing limit. Increasing it as a timeout fix is therefore unsupported by the reviewed API documentation. See the API parameters and job workflow.

3. Check page readiness only when the workflow supports it

For the Screenshots API, use job-level evidence and the API’s documented request options. Do not infer from a timeout alone that lazy loading, JavaScript, network activity, or page height caused it.

If you are actually using Percy for a full-page snapshot, BrowserStack’s Percy guidance recommends ensuring the page has loaded, scrolling to the bottom if lazy-loaded content is missing, and pausing animations, video, and carousels. Its desktop full-page guidance gives a maximum of 10,000 pixels or 10 tiles, whichever is smaller. Those are Percy-specific instructions and limits; they are not documented remedies or limits for the Screenshots API. Read Percy’s full-page guidance.

4. Use an evidence-based troubleshooting sequence

Symptom	Check	Next action
The client call times out, but the job ID was returned	Query the job endpoint or check the callback. The client’s wait and the service’s job result are separate observations.	Use the job state as the source of truth. If the job is still pending, check again according to your application’s polling policy; if it is marked failed or timed out, retain the job details for diagnosis.
The API job says “Timed Out”	Confirm this is the Screenshots API and capture the job ID, URL, requested browsers/devices, timestamp, and exact result.	The documented processing limit is two minutes. Ask BrowserStack Support about a repeatable case; do not assume a request option can extend the cap.
You increased wait_time and the timeout remains	wait_time is documented as a pre-capture delay.	Do not treat it as extra processing time. Inspect job state and confirm the product and error.
An Automate Selenium run reports an idle or socket timeout	Check whether the failure is in an Automate browser session rather than a Screenshots API job.	Apply the Automate timeout documentation for that session. Its documented 90-second idle and 240-second socket periods are distinct from the Screenshots API limit. Automate timeout reference.
A Percy full-page capture omits content or behaves poorly on a long page	Confirm the tool is Percy. Check readiness, lazy-loaded content, animations, video, carousels, and Percy’s page-height guidance.	Follow Percy-specific capture guidance; do not apply its 10,000-pixel/10-tile desktop limit to the Screenshots API. Percy full-page reference.
The timeout occurs only for one URL or browser configuration	Compare the recorded URL, browser/device request, timestamp, and job result across successful and failed cases.	Share that comparison and the job ID with support. The reviewed sources do not establish a universal causal page property or workaround.

5. Improve diagnosis and reliability in your integration

• Keep the job ID. Store it with the requested URL and capture configuration so a later timeout can be tied to the service-side result.
• Separate submission from completion. Treat job creation and final screenshot availability as different steps. Use the documented job endpoint or callback rather than interpreting the initial response as the finished capture.
• Make callback handling safe to retry. Record the job ID and make result processing idempotent so a repeated callback does not create duplicate downstream work. This is an integration design recommendation, not a BrowserStack timeout feature.
• Use a bounded polling policy. Avoid tight polling loops. Choose an interval and overall client wait appropriate to your application, while remembering that client-side waiting does not change the service’s documented processing limit.
• Capture diagnostic context. Preserve the exact error, timestamp, job ID, URL, and browser/device request. Avoid logging credentials or sensitive page content.

Or skip the browser setup

If your task is to get a clean image of a URL rather than debug a BrowserStack job, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. Its cookie and consent handling accepts the banner like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the page verdict and billing status in headers. Its MCP server gives Claude, Cursor, and other MCP clients the take_screenshot, get_page_info, and capture_pdf tools. The documented API docs cover the request options.

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

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for free and get 1,000 screenshots a month with no card.

Performance and cost considerations

For BrowserStack’s Screenshots API, the reviewed sources establish the two-minute per-screenshot processing limit and the asynchronous job workflow, but do not specify how page size affects processing time, a timeout override, or a universal way to make a timed-out job complete. Avoid promising a particular reduction in processing time based on a page change without measuring it in your own workflow and checking the job results.

For ScreenshotNeo, only clean shots are billed: bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing. Plans are Free for 1,000 shots/month with no card; Starter is $5 for 3,000; Growth $15 for 15,000; Pro $39 for 60,000; Scale $99 for 250,000; and Business $249 for 1,000,000. Yearly billing gives two months free, and every feature is on every plan. See the documentation for capture options such as full-page capture with lazy images loaded, selector capture, custom waits, request blocking, caching with a chosen TTL, async jobs, and bulk capture.

FAQ

Does a larger page automatically cause a BrowserStack Screenshots API timeout?

The reviewed BrowserStack sources do not establish that page size alone causes the timeout. The documented behavior is a two-minute processing limit per screenshot.

Can I raise the two-minute limit?

The reviewed API documentation does not document an option to raise it. Confirm with BrowserStack Support if you need an authoritative answer for your account or workflow.

Does wait_time give the screenshot more time to finish?

It is documented as a delay before capture. The reviewed documentation does not say it extends the processing limit.

Does Percy’s full-page height limit apply to the Screenshots API?

No such connection is established in the reviewed sources. The cited height guidance belongs to Percy’s full-page workflow.

What should I send support for a recurring timeout?

Provide the job ID, URL, requested browsers/devices, timestamp, and exact error. This gives support the identifying details of the specific job.