How do I take a screenshot with the Browserless REST API? Send an authenticated POST request to Browserless’s current /screenshot endpoint, include either a url or inline html in the JSON body, and save the binary response as an image. Add options for full-page capture, viewport size, clipping, quality, format, waits, navigation, or resource blocking. This guide shows runnable requests, explains the important options, and covers the failure modes that produce blank or incomplete images.
What the Browserless Screenshot API does
Browserless runs a browser for one render-and-capture task and returns image bytes. Its REST API is designed for a single HTTP request rather than for you to operate Chromium infrastructure; Browserless describes REST APIs as useful “when you want a single HTTP request to do one browser task without managing browser infrastructure.” See the REST API overview.
The current endpoint is documented at Screenshot API. Authentication uses an account token in the token query parameter. The request body is JSON, and the successful response is binary image data rather than JSON metadata.
URL mode versus HTML mode
- URL mode: send
urland let Browserless navigate to a page. - HTML mode: send
htmlcontaining the markup to render.
When using HTML mode, do not also send url; the current guide explicitly cautions against including both fields in the same request.
#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
Minimal request: capture a URL
The smallest useful request is a JSON POST with a URL and your token. This cURL example writes the returned PNG to disk:
curl -X POST "https://chrome.browserless.io/screenshot?token=YOUR_TOKEN"
-H "Content-Type: application/json"
-d '{"url":"https://example.com"}'
-o example.pngReplace YOUR_TOKEN with the token from your Browserless account. Treat it as a secret: keep it in an environment variable or server-side secret store, not in browser JavaScript or a public repository. The response body is the image, so your client must write bytes without trying to parse JSON.
Check the HTTP response before saving
A production client should verify the status code and content type before treating the body as an image. A 401 or 403 usually indicates a missing, invalid, or exhausted credential; a 4xx request error means the JSON or option names need correction; a 5xx response indicates a service-side failure that may be retryable.
Capture supplied HTML instead of navigating
Use inline HTML when the page is generated by your application or you need a deterministic fixture. Do not include a url field in this mode:
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutecurl -X POST "https://chrome.browserless.io/screenshot?token=YOUR_TOKEN"
-H "Content-Type: application/json"
-d '{
"html":"<!doctype html><html><body><h1>Invoice 1042</h1><p>Paid</p></body></html>"
}'
-o invoice.pngExternal fonts, images, scripts, and styles referenced by that HTML still need to be reachable from the browser. If you need a fully repeatable render, inline critical CSS and assets or make sure the referenced resources are available before capture.
Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
Choose the capture scope and image format
The current REST documentation lists PNG, JPEG, and WebP responses. Capture settings are supplied through options, except for element selection, where the guide places selector at the top level.
| Need | Setting | Practical use |
|---|---|---|
| Viewport only | Default screenshot behavior | Capture what a browser user sees at the configured viewport. |
| Entire document | options.fullPage |
Produce a long image containing the page, including content below the fold. |
| One element | Top-level selector |
Capture a chart, card, article, or other CSS-selected node. |
| Fixed rectangle | options.clip |
Capture a known x/y region with a defined width and height. |
| Smaller files | Format and quality options | Use JPEG or WebP when lossless PNG is unnecessary. |
| Sharper output | Viewport and device scale factor options | Render at a larger pixel density for documentation or retina displays. |
Full-page screenshot
A full-page image is useful for visual regression, archiving, and sharing a page as one file. Long pages often load content lazily, however. Browserless recommends scrolling before a full-page capture so images and other below-the-fold content have a chance to load.
curl -X POST "https://chrome.browserless.io/screenshot?token=YOUR_TOKEN"
-H "Content-Type: application/json"
-d '{
"url":"https://example.com/article",
"options":{"fullPage":true}
}'
-o article-full.pngCapture one element by CSS selector
To capture only a particular element, put the selector at the body’s top level:
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →curl -X POST "https://chrome.browserless.io/screenshot?token=YOUR_TOKEN"
-H "Content-Type: application/json"
-d '{
"url":"https://example.com/dashboard",
"selector":".revenue-chart"
}'
-o chart.pngUse a selector that identifies one stable element. A class generated anew on every deployment, or a selector matching several nodes, can lead to an error or an unexpected capture. For a fixed rectangle rather than a DOM node, use options.clip with the documented coordinates and dimensions.
Viewport, scale, quality and format
Set the viewport to match the responsive layout you want to test. A narrow width can trigger a mobile breakpoint, while a wide width can reveal desktop navigation. Device scale factor controls the number of output pixels per CSS pixel. Quality applies to lossy formats such as JPEG and WebP; PNG is lossless and does not use JPEG-style quality compression. Confirm the exact option spelling and accepted values in the current endpoint guide before deploying, because option schemas can change.
Rank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
Wait for dynamic pages before taking the shot
Navigation finishing does not always mean the page is visually ready. Browserless documents waits based on events, functions, selectors, or timeouts, plus navigation controls through gotoOptions. Choose the narrowest condition that represents readiness:
- Selector wait: wait for a chart, product grid, or other known node.
- Function wait: wait for an application-specific condition, such as a global “data loaded” flag.
- Event wait: use a browser event when your page exposes one.
- Timeout wait: a fallback for pages with no reliable readiness signal; it is less deterministic.
For example, a request can combine a URL with a selector wait and full-page capture (use the exact wait object shape shown in the current documentation):
curl -X POST "https://chrome.browserless.io/screenshot?token=YOUR_TOKEN"
-H "Content-Type: application/json"
-d '{
"url":"https://example.com/app",
"options":{"fullPage":true},
"waitForSelector":"main[data-ready="true"]"
}'
-o app.pngIf the page’s data arrives after a client-side request, a selector wait is generally preferable to an arbitrary sleep. If you use a timeout, allow enough time for the slowest normal response but keep a maximum that prevents hung jobs from consuming resources indefinitely.
Navigation and resource controls
gotoOptions lets you tune navigation behavior for the target page. The screenshot API also documents rejecting selected resource types or request patterns. Blocking advertising, analytics, video, or other nonessential requests can reduce noise and speed a capture, but blocking a stylesheet, font, API call, or image required by the layout will change the result.
- Start with no blocking while you establish a correct baseline.
- Add one resource rule at a time and compare the image.
- Never block the API or script that supplies content you expect to appear.
- Use a wait condition after blocking to confirm the remaining page is ready.
Python implementation
This complete example posts JSON, checks for an HTTP error, validates that a response was received, and writes the image bytes:
Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
import os
import requests
TOKEN = os.environ["BROWSERLESS_TOKEN"]
payload = {
"url": "https://example.com",
"options": {"fullPage": True}
}
response = requests.post(
"https://chrome.browserless.io/screenshot",
params={"token": TOKEN},
json=payload,
timeout=90,
)
response.raise_for_status()
content_type = response.headers.get("content-type", "")
if not content_type.startswith("image/"):
raise RuntimeError(f"Expected image data, got {content_type}")
with open("example.png", "wb") as output:
output.write(response.content)
Install the dependency with python -m pip install requests and set BROWSERLESS_TOKEN in the process environment. Change the output extension and requested format together so downstream systems do not mistake a WebP or JPEG for PNG.
Free tools Windows power users keep installed
One-click scans. No signup required.
Node.js implementation
In modern Node.js, use the built-in fetch and write the returned ArrayBuffer:
import { writeFile } from "node:fs/promises";
const token = process.env.BROWSERLESS_TOKEN;
const response = await fetch(
`https://chrome.browserless.io/screenshot?token=${encodeURIComponent(token)}`,
{
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
url: "https://example.com",
options: { fullPage: true }
})
}
);
if (!response.ok) {
throw new Error(`Browserless returned ${response.status}: ${await response.text()}`);
}
const type = response.headers.get("content-type") || "";
if (!type.startsWith("image/")) throw new Error(`Unexpected content type: ${type}`);
await writeFile("example.png", Buffer.from(await response.arrayBuffer()));
How to make captures reliable
Use deterministic page state
For visual tests, freeze dates, random values, feature flags, and user-specific data where possible. Supply authentication through the page’s supported mechanism rather than embedding long-lived credentials in a public URL. If the page changes by locale, set the locale-related navigation or request settings explicitly and record the choice with the artifact.
Handle lazy loading
A full-page command can finish before images below the fold have entered the viewport. Scroll the page before the screenshot, or wait for a page-specific “all content loaded” signal. If only one component matters, element capture avoids unrelated lazy content and produces a smaller artifact.
Control output size
Very wide viewports, high device scale factors, and extremely long documents create large images. Large responses increase transfer time and memory use in your client. Prefer a targeted selector or clip when a whole-page image is not required, and choose WebP or JPEG when your downstream workflow accepts lossy compression.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsBest Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
Retry carefully
Retry transient network or 5xx failures with bounded exponential backoff. Do not blindly retry invalid JSON, authentication errors, selector-not-found errors, or a page that consistently returns a CAPTCHA; those require a changed request or an access decision. Give each capture a request ID in your own logs, record the URL and option set, and store the HTTP status and content type.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Blocked pages, CAPTCHAs and blank results
Browserless warns that sites blocking automation can produce blank captures, CAPTCHA pages, access-denied results, or missing elements. These outcomes can be caused by the target site, not by a malformed screenshot request. Browserless documents a separate /unblock API for some bot-detection situations, followed by a screenshot response; it does not promise that every protected site can be captured.
Diagnose the symptom
- Blank white image: check whether the page requires JavaScript, whether navigation timed out, and whether a blocked resource supplied the visible content.
- CAPTCHA or access denied: treat the response as a protected-site result; do not represent it as a successful screenshot.
- Missing lower-page content: scroll or wait for lazy-loaded elements before full-page capture.
- Missing selected element: verify the selector, wait for it explicitly, and confirm that it exists in the same navigation state.
- Image opens as corrupted: inspect the status and content type; you may have saved an error body as if it were image bytes.
Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| 401 or 403 | Token missing, invalid, or not authorized. | Pass the token query parameter, check the account, and keep the token server-side. |
| 400-level validation error | Malformed JSON, unsupported option, or both url and html supplied. |
Send valid JSON, use documented option names, and choose exactly one input mode. |
| Timeout | Slow navigation, an unreachable dependency, or a wait that never becomes true. | Inspect the URL, raise the navigation/wait allowance prudently, or replace an unreliable wait condition. |
| Wrong crop | Clip coordinates do not match the viewport, or the target moved responsively. | Set the intended viewport first and use a stable selector when possible. |
| Unexpected format | Requested format and filename or downstream decoder disagree. | Read the Content-Type header and use a matching extension and decoder. |
Version and endpoint care
Use the current REST screenshot documentation, not old snippets copied from legacy tutorials. Browserless marks its BaaS v1 screenshot page as deprecated and directs users to updated BaaS v2 or BrowserQL documentation: legacy BaaS v1 screenshot API. The current REST guide is the appropriate reference for endpoint fields and option syntax.
Browserless or ScreenshotNeo?
ScreenshotNeo is the first alternative to try when you want clean production screenshots: cookie banners, newsletter popups, and chat widgets are removed before capture, and only clean shots are billed. It supports PNG, JPEG, WebP, PDF, URL or HTML capture, full-page and selector shots, custom waits, headers, cookies, user agents, JavaScript, request blocking, device presets, signed links, asynchronous webhooks, bulk capture, and an MCP server for AI agents. Browserless is a strong fit when you specifically want its browser-oriented REST workflow and documented navigation controls; ScreenshotNeo is aimed at delivering a clean asset with less page-overlay cleanup.
Or skip the browser setup
One GET request returns the image. The API removes cookie/consent banners, popups, and chat widgets before capture; bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, with X-Page-Verdict and X-Billed headers explaining the result. Its MCP server lets Claude, Cursor, and other MCP clients call take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 screenshots each month with no card, and paid plans start at $5 for 3,000 shots.
cURL (see the ScreenshotNeo documentation):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Create a free ScreenshotNeo account to get 1,000 screenshots per month without a card.
FAQ
Can I capture a full-page screenshot via the API?
Yes. Set the documented full-page option, and scroll or wait first when the page uses lazy loading.
Can I capture just one element?
Yes. Put the CSS selector in the request body’s top-level selector field rather than inside options.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Does the endpoint return JSON?
No. A successful screenshot response is image data. Save the bytes and inspect the status and Content-Type before decoding.
Can Browserless bypass every CAPTCHA?
No. Browserless documents /unblock for some bot-detection cases, but protected sites can still return CAPTCHA, access-denied, blank, or incomplete results.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
