How to Take a Full-Page Screenshot with the Browserless Screenshot API
Capture a full rendered page with Browserless: send a POST request with fullPage enabled, handle lazy-loaded content, and save the returned image bytes.
To take a full-page screenshot with the current Browserless Screenshot REST API, send a POST request to /screenshot, set options.fullPage to true, and save the binary response as an image. If the page loads content as it is scrolled, also set top-level scrollPage to true.
1. Make a full-page screenshot with cURL
This documented REST request captures the rendered page as PNG. Replace the token with your Browserless API token and use the host assigned to your account or fleet.
curl -X POST \
"https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE" \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
"url": "https://example.com/",
"options": {
"fullPage": true,
"type": "png"
}
}' \
--output "screenshot.png"The endpoint returns image bytes, not a JSON response. The --output flag writes those bytes to a file. Do not print the response to a terminal or try to parse it as JSON. Keep the real token private; avoid committing it to source control or exposing it in client-side code.
2. Capture lazy-loaded page content
A full-page capture can miss images or sections that only load after they enter the viewport. Ask Browserless to scroll the page before capturing by adding scrollPage: true at the top level of the request body, alongside url and options:
{
"url": "https://example.com/",
"scrollPage": true,
"options": {
"fullPage": true,
"type": "png"
}
}Scrolling can trigger common viewport-based lazy loading, but it cannot guarantee content that requires a click, form submission, authentication, or some other interaction. Inspect captures of pages with unusual loading behavior and choose a browser workflow that supports the required interaction when one REST action is insufficient.
3. Save the response in Python
Use an HTTP client to send the JSON body and write the response bytes directly to a file. Install the dependency with python -m pip install requests.
import requests
endpoint = "https://production-sfo.browserless.io/screenshot"
params = {"token": "YOUR_API_TOKEN_HERE"}
payload = {
"url": "https://example.com/",
"scrollPage": True,
"options": {
"fullPage": True,
"type": "png",
},
}
response = requests.post(
endpoint,
params=params,
json=payload,
headers={"Cache-Control": "no-cache"},
timeout=90,
)
response.raise_for_status()
with open("screenshot.png", "wb") as image_file:
image_file.write(response.content)The timeout is a client-side limit in this example; choose one appropriate to your own request budget. A successful HTTP status alone does not tell you whether the page displayed the intended content, so review the resulting image when correctness matters.
4. Save the response in JavaScript with Node.js
This example uses the built-in fetch and file APIs available in current Node.js releases. It buffers the returned image bytes and writes them as a PNG.
import { writeFile } from "node:fs/promises";
const endpoint = new URL("https://production-sfo.browserless.io/screenshot");
endpoint.searchParams.set("token", "YOUR_API_TOKEN_HERE");
const response = await fetch(endpoint, {
method: "POST",
headers: {
"Cache-Control": "no-cache",
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://example.com/",
scrollPage: true,
options: {
fullPage: true,
type: "png",
},
}),
signal: AbortSignal.timeout(90_000),
});
if (!response.ok) {
throw new Error(`Browserless returned HTTP ${response.status}: ${await response.text()}`);
}
await writeFile("screenshot.png", Buffer.from(await response.arrayBuffer()));Do not use response.json() for a successful image response. For production services, load the token from a server-side secret store or environment configuration rather than hard-coding it.
5. Choose the screenshot options you need
The current REST Screenshot API accepts Puppeteer-style screenshot settings under options. For the full rendered document, fullPage: true is the key setting. The current REST overview documents PNG, JPEG, and WebP output. Use the format that fits the next step in your pipeline, and ensure the filename extension matches the selected type.
| Need | Setting or approach | Notes |
|---|---|---|
| Entire rendered document | options.fullPage: true |
Captures beyond the visible viewport. |
| Viewport only | Omit full-page capture or set it false | Useful when only the initially visible region is needed. |
| Lazy-loaded sections | Top-level scrollPage: true plus full-page capture |
Scrolling may trigger loading tied to entering the viewport. |
| Image format | options.type: PNG, JPEG, or WebP |
PNG is lossless; JPEG and WebP may suit smaller image payloads. Confirm the accepted spelling and settings in the current REST documentation. |
| Page dimensions or device scale | Screenshot viewport and scale settings | Use the current REST schema for exact field names and supported values. |
| Only a region or element | Clip or selector-related options where supported | This changes the capture target; it is not a substitute for full-page output. |
| Wait for page content | Documented wait options | Choose a wait that matches how the target page signals readiness; avoid assuming a fixed delay fits every site. |
Browserless also documents options related to viewport size, device scale factor, clipping, selectors, and waits. Check the current REST API reference for the exact request shape before relying on an option: BrowserQL and REST schemas are separate interfaces, and their defaults or field names may differ. In particular, BrowserQL schema defaults such as waitForImages or screenshot timeout should not be assumed to apply to the REST endpoint.
6. Understand full-page capture edge cases
Long or dynamically changing pages
Long pages can take longer to load, scroll, and encode than viewport captures. Infinite-scroll pages may continue adding content as the browser scrolls, so decide what constitutes a complete capture for that page. If the page changes while capture is underway, a single image may not represent a consistent point in time.
Content that needs interaction
A REST screenshot request is a stateless, single-action job. It does not preserve a browser session or provide real-time interaction during the request. If a page requires clicking a consent control, signing in, or carrying state across steps, use a workflow designed for sessions or interaction rather than expecting one screenshot request to perform an arbitrary sequence.
Bot challenges and access restrictions
A target can return a CAPTCHA, access-denied page, HTTP 403 content, or another bot challenge instead of the intended page. Browserless documentation describes possible routes such as its unblock API or residential proxies, while noting that bot-detection bypass is limited. These approaches do not guarantee access to every site; only capture pages you are authorized to access.
Shared and private fleets
The production SFO URL above is the documented example host. Browserless provides different endpoint arrangements for shared and private fleets. Use the endpoint assigned to your account rather than copying the example host when your deployment specifies another one.
7. Troubleshoot common failures
| Symptom | Likely cause | What to do |
|---|---|---|
| The saved file is not a readable image | The response was an error body, or the request used the wrong output handling. | Check the HTTP status and error response before writing bytes; save successful response bytes in binary mode and match the file extension to the requested format. |
| The image shows only the first screen | fullPage is missing, false, or placed outside options. |
Set options.fullPage to true in the JSON body. |
| Images or sections are missing | Content may load only when scrolled into view. | Add top-level scrollPage: true with options.fullPage: true. Check whether the content still needs an interaction or longer readiness wait. |
| The screenshot contains a CAPTCHA, denial, or blank page | The target may block automated browsers, fail to load, or serve a challenge. | Inspect the returned image and HTTP response. Browserless documents unblock and proxy options, but success varies by target and protection. |
| HTTP authentication or token error | The token is absent, invalid, or used with the wrong fleet host. | Verify the token and account-assigned endpoint; keep credentials out of public code and logs. |
| Request times out | The target is slow, the page is very long, or the client timeout is too short. | Check the destination’s load behavior, choose a suitable client timeout, and avoid treating an arbitrary fixed wait as proof that content is ready. |
| Code expects JSON but gets binary data | The endpoint returns image data for a successful screenshot. | Read the response as bytes or an array buffer. Read text only when diagnosing an error response. |
8. Performance, reliability, and cost considerations
Full-page captures process more page content than viewport screenshots, so very tall pages and large images can take longer and produce larger files. JPEG or WebP may reduce output size compared with PNG depending on content, while PNG preserves lossless image data. Pick based on downstream fidelity and storage needs rather than assuming one format is always smaller.
Reliability depends on the target page as well as the screenshot service: network delays, client timeouts, dynamic content, bot protection, and page changes can all affect what is captured. For a production pipeline, check HTTP status, retain enough response context to diagnose failures, use bounded retries for transient errors, and avoid retrying permanent authentication or access-denied failures indefinitely. A successful request does not itself validate that the intended page content appears in the image.
Browserless usage and pricing depend on the account and deployment. The research sources do not establish a price or a cost per full-page capture, so consult your current Browserless plan and account details before estimating spend. Also account for downstream storage and transfer of large image files.
9. Browserless Screenshot API versus a persistent browser
Use the one-shot REST Screenshot API when the task is to load a URL and capture it in one request. The REST workflow launches a browser, performs the requested action, and closes it; it does not preserve session state or support live interaction. If your capture depends on multi-step clicks, continuing login state, or an interactive session, Browserless documents BaaS sessions or BrowserQL persisted state as alternatives to investigate.
For full-page versus viewport capture, use full-page output when the whole rendered document is the deliverable. Use viewport output when the visible region is sufficient and smaller output or faster processing matters.
10. Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. One GET request can return a screenshot as PNG, JPEG, or WebP, or a PDF. See the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://example.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000 screenshots. Sign up for free and get 1,000 screenshots a month with no card.
11. FAQ
Does the endpoint return a URL to the screenshot?
No. A successful request returns the image data in the response, which your client should save or pass to another binary-aware step.
Can a single REST request preserve a login for the next capture?
No. The documented REST workflow is stateless. Use a session-based browser workflow when captures need continuing state.
Is the old Chrome BaaS v1 screenshot URL still the recommended endpoint?
No. Browserless marks its older BaaS v1 Screenshot API instructions deprecated and directs new usage to current BaaS v2 or BrowserQL documentation. This guide uses the current REST Screenshot API.
Will scrolling capture every item on an infinite-scroll page?
Not necessarily. It can trigger lazy loading, but pages that load indefinitely or require specific interactions need page-specific handling and a clear stopping condition.
