How to Automate Full-Page Website Screenshots with BrowserCat in Node.js

Use Playwright’s fullPage: true screenshot option after connecting to BrowserCat’s hosted Chromium session. The connection uses BrowserCat’s WebSocket endpoint and an Api-Key header. Wait for the content your target page needs before capturing; a full-page screenshot controls the capture area, but does not guarantee that asynchronous content or lazy-loaded images are ready.

1. Set up Node.js and BrowserCat

BrowserCat’s quick start recommends Playwright for a first setup. Create a BrowserCat account and API key, then keep the key in an environment variable or secret store rather than committing it to your project.

Install Playwright Core, which provides the Playwright API without launching a local browser:

npm init -y
npm install playwright-core

Save the following as screenshot.mjs. The example uses Node.js’s built-in fetch only indirectly; the screenshot is saved by Playwright to a local file.

import { chromium } from 'playwright-core';

const apiKey = process.env.BROWSERCAT_API_KEY;
if (!apiKey) {
  throw new Error('Set the BROWSERCAT_API_KEY environment variable.');
}

const browser = await chromium.connect('wss://api.browsercat.com/connect', {
  headers: { 'Api-Key': apiKey },
});

try {
  const page = await browser.newPage();
  await page.goto('https://example.com', { waitUntil: 'load' });
  // Replace this with a selector for the content you need on dynamic pages.
  await page.screenshot({ path: 'page.png', fullPage: true });
} finally {
  await browser.close();
}

Run it with the key in the process environment:

BROWSERCAT_API_KEY=YOUR_API_KEY node screenshot.mjs

This combines BrowserCat’s documented Playwright connection pattern with Playwright’s documented fullPage: true option. The combination is an implementation pattern; it is not presented as independently tested here.

2. Capture the full scrollable page

Playwright documents page.screenshot({ path: 'screenshot.png', fullPage: true }) as capturing the full scrollable page as if it were shown on one very tall screen. Use path to write the image to disk. To get image bytes for further processing instead, omit path and keep the returned buffer:

const imageBuffer = await page.screenshot({ fullPage: true });

The buffer form lets your application decide how to store or process the image. The file form is simpler when you want a local artifact.

3. Wait for the content your page needs

waitUntil: 'load' waits for the page load event, but websites often render important content afterward. Wait for a page-specific selector when you know what signals readiness:

await page.goto('https://example.com/products', { waitUntil: 'load' });
await page.locator('[data-testid="product-grid"]').waitFor();
await page.screenshot({ path: 'products.png', fullPage: true });

Choose a selector that appears only when the content you need is present. If a page has no reliable selector, a short fixed delay can be used as a fallback, but it may waste time on fast loads and still be too short on slow ones. Validate screenshots against the actual target page, especially if it has animations, web fonts, asynchronous requests, or lazy-loaded images.

The reviewed documentation does not establish that BrowserCat automatically scrolls through pages to trigger lazy-loaded content. A full-page capture sets the screenshot extent; it should not be treated as proof that every image or section has been loaded.

4. Choose local or hosted browser execution

With a local Playwright browser, the usual workflow launches a browser with chromium.launch(). BrowserCat’s hosted workflow connects with chromium.connect() to wss://api.browsercat.com/connect and supplies the API key in an Api-Key header. The rest of the page navigation and screenshot calls use Playwright’s page API.

BrowserCat’s quick start describes its sessions as cloud Chromium sessions. Use the hosted connection when you want the browser session to run through BrowserCat; use a local launch when you specifically need a browser process on your own machine.

5. BrowserCat connection configuration

BrowserCat’s browser configuration guide documents a BrowserCat-Opts header and query parameters for configuration. If a setting is supplied in both places, the header value takes precedence. The key connection detail for this tutorial is the Api-Key header shown above.

The guide cautions that credentials passed as query parameters must travel only over HTTPS or WSS. Prefer the header pattern in the example so the key is not placed in the connection URL. Consult BrowserCat’s current configuration documentation for the exact supported options and formats before adding configuration to a production connection.

6. Or skip the browser setup

If you only need the screenshot, ScreenshotNeo provides a one-request screenshot API. See the ScreenshotNeo API documentation for the available parameters.

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,
)
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}`);

Cookie banners are accepted and removed before capture; ScreenshotNeo also removes known consent platforms, newsletter popups, and chat widgets. Each of those steps can be turned off.
Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing. Response headers report the page verdict and billing status.
An MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs.
The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is on every plan.

7. Troubleshooting

Symptom	Likely cause	What to do
Connection fails or is rejected	The API key is missing, invalid, or not being sent as the expected header.	Confirm `BROWSERCAT_API_KEY` is set in the environment and passed as `Api-Key`. Check the current BrowserCat quick start for account and key setup.
The script cannot import `playwright-core`	The package is not installed in the project or the script is run from a different project directory.	Run `npm install playwright-core` in the project, then run the script there.
The screenshot is missing late content	The page rendered that content after the selected navigation event.	Wait for a page-specific locator that marks the content as ready before capturing.
Lazy images are blank or absent	The page may load images only as they approach the viewport; the screenshot option alone does not establish that they loaded.	Inspect the target page’s loading behavior and use a page-specific readiness approach. Verify the resulting capture rather than assuming all lazy content was triggered.
The script exits before a screenshot is written	Navigation, readiness waiting, or capture may have thrown an error.	Read the thrown error and verify the URL, readiness selector, and connection. The `finally` block closes the browser even when an operation fails.
A configured setting has no effect	The same option may have been provided in both the configuration header and query parameters.	BrowserCat documents that header values win when both are present; remove the duplicate or update the header value.

8. Performance, reliability, and cost

A full-page image can be much larger than a viewport screenshot because it includes the entire scrollable page. Use a file path when you need a straightforward local output, and a buffer when a later step needs the image bytes. Waiting for a meaningful selector helps avoid capturing too early; an arbitrary long delay can add latency without guaranteeing readiness.

The BrowserCat materials cited here describe the hosted connection workflow but do not provide pricing, performance benchmarks, uptime figures, or universal guarantees about page readiness. Check BrowserCat’s current documentation and account details for service-specific terms. For reliability, handle navigation and capture errors in your application, close the browser in a finally block, and inspect representative screenshots from the pages you plan to capture.

9. Frequently asked questions

Does `fullPage: true` scroll the page?

It requests a screenshot of the full scrollable page. It does not, by itself, guarantee that page-specific lazy content has been loaded.

Can I capture a screenshot without saving a file?

Yes. Call page.screenshot({ fullPage: true }) without path and use the returned buffer.

Can I use the same page code with a local browser?

The capture calls use Playwright’s page API. The browser setup differs: BrowserCat’s hosted workflow uses connect(), while a local browser workflow uses launch().

Does a load event mean the screenshot is ready?

Not for every site. Wait for the specific content you need and check the resulting image.