How to Capture a Scrolling Webpage Screenshot with Browserless

To capture a scrolling webpage with Browserless, send a POST request to its /screenshot endpoint with options.fullPage: true. If the page loads images or other content as it scrolls into view, also set the top-level scrollPage: true. The endpoint returns image bytes, which you can save directly to a file. You need a Browserless API token. [Browserless Screenshot API]

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/",
    "scrollPage": true,
    "options": {
      "fullPage": true,
      "type": "png"
    }
  }' \
  --output "screenshot.png"

Use the region endpoint associated with your Browserless account. Keep the token private; do not put it in client-side code or commit it to a repository.

1. Understand what “scrolling screenshot” means

A viewport screenshot captures only what is visible in the browser window. A full-page screenshot captures the document beyond the viewport. Setting fullPage: true asks Browserless to capture that full document.

Some pages defer loading images or content until those sections approach the viewport. A full-page capture alone may not trigger that behavior. Browserless’s REST screenshot API supports scrollPage: true to scroll before capturing. The scroll gives scroll-triggered content a chance to load, but it cannot guarantee that every infinite-scroll feed or page-specific interaction will be fully captured. [Screenshot API]

2. Make a full-page capture with cURL

Replace YOUR_API_TOKEN_HERE with your Browserless API token.
Replace the example URL with the page you want to capture.
Keep scrollPage enabled if the page has lazy-loaded content.
Run the request and save the returned image bytes to a file.

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/",
    "scrollPage": true,
    "options": {
      "fullPage": true,
      "type": "png"
    }
  }' \
  --output "screenshot.png"

The successful response is image data, not a JSON object containing an image URL. Use an output file or otherwise handle the response as binary data. [Browserless screenshot example]

3. Choose the capture settings

Need	Setting or approach	What to consider
Capture beyond the visible viewport	`options.fullPage: true`	Captures the full document rather than just the current viewport.
Trigger scroll-based loading	`scrollPage: true` in the REST request	Useful for content that appears only after scrolling. It does not make an unbounded infinite-scroll page finite.
Represent a particular device layout	Set the viewport in a connected-browser workflow before capture	Viewport width affects responsive layout and therefore the screenshot. Browserless documents viewport configuration in its BAP screenshot guide.
Save a lossless image	`type: "png"`	PNG quality settings do not apply.
Reduce image size	Choose JPEG or WebP where supported; set quality for lossy formats	Check the options supported by the specific Browserless interface you use.
Capture one element	Use the documented selector option	Useful when the target is one component instead of the whole document.
Capture a fixed region	Use `clip` with coordinates and dimensions	Choose the region with the page layout and viewport in mind.
Wait for images	Use the BAP `waitForImages` option in a BAP workflow	Options are interface-specific; do not assume every BAP setting is accepted by the REST endpoint.
Transparent background	BAP `omitBackground`	Confirm support for the endpoint and output format in use.

Browserless documents screenshot formats, selectors, clipping, viewport settings, and BAP image options in its Screenshots and PDFs with BAP guide. Check the endpoint’s own options before combining settings across interfaces.

4. Handle pages that need more than a scroll

Use the REST endpoint when the task is simply “open this URL and return an image.” If capture depends on a custom wait, navigation condition, click, or other page interaction, use a connected-browser workflow so your code can operate on the page before taking the screenshot. Browserless documents connected Puppeteer, Playwright, and BAP workflows. [Screenshot API, Take a screenshot]

For BAP, the documented page interaction method can scroll through the document in viewport-sized steps and return to the top. Then take the full-page screenshot:

await page.scroll({ throughPage: true });
await page.screenshot({ fullPage: true });

This is a BAP example, not a REST request body. Use the API’s documented syntax for the Browserless interface you selected. [Interacting with pages in BAP]

Scrolling can trigger content that is tied to viewport visibility. It may not handle a page that requires clicking a “load more” control, dismissing a blocking dialog, or repeatedly fetching new items as the user reaches the bottom. Those cases need page-specific interaction. Browserless documents page interaction separately from the REST screenshot request; this distinction is why a connected workflow is appropriate when the page needs custom actions.

5. REST screenshot versus PDF

A screenshot is a rendered image. Browserless’s PDF endpoint uses Chrome’s print pipeline, and its REST PDF API does not produce one continuous long-page PDF for the entire webpage. If you need a long image, use /screenshot. For a custom full-page PDF workflow, Browserless points to its /function API. [Browserless PDF API]

6. Troubleshooting

Symptom	Likely cause	What to try
Only the first screen appears	The capture is using viewport mode.	Set `options.fullPage` to `true`.
Images or sections are missing lower down	The page loads them only when scrolled into view.	Set top-level `scrollPage: true` for REST, or scroll through the page in a BAP workflow before capturing.
Some content remains missing after scrolling	The page may require a custom action, wait, or repeated loading as the visitor reaches the bottom.	Use a connected-browser workflow and add the page-specific interaction or wait. A single scroll preparation is not a guarantee for every dynamic page.
The layout is the wrong size or breakpoint	The viewport does not match the device layout you intended.	Set the viewport in a connected-browser workflow before navigation and capture. Browserless documents viewport settings in its BAP guide.
The output file is unusable or contains an error response	The request may have failed, or the response may not be image bytes.	Check the HTTP response and request details before treating the body as an image; confirm the token, endpoint, URL, and JSON structure.
PNG quality settings have no effect	PNG is lossless and does not use lossy quality controls.	Use JPEG or WebP if you need a quality/compression trade-off, where supported by the chosen endpoint.
A PDF is paginated rather than one long page	The REST PDF endpoint uses the print-document workflow.	Use the screenshot endpoint for a long image, or investigate Browserless’s documented custom `/function` approach for full-page PDF generation.

7. Performance, reliability, and cost considerations

Full-page images can be much taller and larger than viewport captures. Choose a lossy format and quality setting when smaller files matter more than lossless fidelity, and capture only a selector or clip when the whole page is unnecessary. The documentation describes these choices but does not provide a universal size or speed benchmark; results depend on the target page and capture settings.

Scrolling and waiting for images can improve completeness on lazy-loaded pages, while adding work before the capture. Pages with long or dynamic content may need a connected workflow and explicit handling. Treat a successful HTTP response and a valid image file as separate checks in your application, especially when you save binary responses automatically.

Browserless is a managed browser service; its platform and screenshot documentation describe the hosted capture workflow. [Browserless platform] Review your account’s current plan and usage terms for cost details; the cited technical documentation does not establish a price for this request.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a screenshot, and the parameter names used by other screenshot APIs also work, which can make switching easier. See the ScreenshotNeo API documentation.

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

import 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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const bytes = new Uint8Array(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', bytes));

ScreenshotNeo removes cookie and consent banners, newsletter 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; paid plans start at $5 for 3,000 screenshots.

FAQ

Does `scrollPage: true` mean Browserless captures every item in an infinite feed?

No. It scrolls to trigger scroll-based loading, but a feed that keeps adding content may need page-specific interaction and a defined stopping condition.

Does full-page mean mobile-sized?

No. Full-page controls vertical coverage. The viewport determines the rendered width and responsive layout.

Can I use the screenshot response as JSON?

The documented REST quickstart returns image data. Save or process the response as binary bytes.

Which format should I choose?

Use PNG when lossless output matters. Choose JPEG or WebP when a smaller lossy image is appropriate and the endpoint supports it.