How to Use the BrowserCat API to Capture a Full-Page Screenshot

To capture a full-page screenshot with BrowserCat, connect Playwright to its hosted Chromium browser over the WebSocket endpoint, navigate to the target page, then call page.screenshot({ fullPage: true }). BrowserCat documents a remote browser connection followed by Playwright page methods; the screenshot operation is Playwright’s page API, not a dedicated BrowserCat screenshot REST endpoint. BrowserCat’s Playwright guide and Playwright cheatsheet show this flow.

1. Prepare Playwright and BrowserCat

You need Node.js, Playwright, a BrowserCat account, and an API key. Install Playwright in a project:

npm install playwright

Keep the API key in an environment variable rather than committing it to source control. In a shell, set BROWSERCAT_API_KEY to the key from your BrowserCat account. The code below reads it from the environment.

2. Connect and capture the full page

Save this as screenshot.mjs. It writes a PNG to page.png. Replace the target URL with a page you are authorized to capture.

import * as playwright from 'playwright';

const apiKey = process.env.BROWSERCAT_API_KEY;
if (!apiKey) {
  throw new Error('Set BROWSERCAT_API_KEY before running this script.');
}

const browser = await playwright.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',
    timeout: 60_000,
  });

  await page.screenshot({ path: 'page.png', fullPage: true });
  console.log('Saved page.png');
} finally {
  await browser.close();
}

Run it with BROWSERCAT_API_KEY set in the process environment. The remote connection endpoint and Api-Key header follow BrowserCat’s documented Playwright connection pattern. See the connection guide and quick start.

What “full page” means

fullPage: true tells Playwright to capture the full document rather than only the current viewport. The method returns image bytes if no path is supplied; adding path writes the image to disk. BrowserCat’s reference demonstrates full-page capture and PNG/JPEG output paths.

Read the image into memory instead

For an upload, storage client, or image-processing step, omit path and use the returned buffer:

const image = await page.screenshot({ fullPage: true });
// `image` is a Buffer. For example:
await import('node:fs/promises').then(({ writeFile }) => writeFile('page.png', image));

3. Choose readiness and output settings

There is no wait condition that guarantees every website has finished rendering every image and application widget. Pick a readiness signal that matches the target page, then capture. The goto timeout is an upper bound for navigation, not a guarantee that the page is useful or visually complete.

Need	Approach	Tradeoff
Document and dependent resources loaded	waitUntil: 'load'	Often a reasonable default; client-side rendering can continue afterward.
DOM is available	waitUntil: 'domcontentloaded'	Earlier capture; images and other resources may still be loading.
Application-specific content	Wait for a selector or app signal, such as await page.locator('[data-ready="true"]').waitFor()	Most reliable when the site exposes a stable readiness marker.
Network appears quiet	Use an appropriate network-idle wait only when the site permits it	Analytics, polling, and streaming can keep a page active or make “idle” misleading.

For a known page element, wait for it before capturing:

await page.goto('https://example.com/report', { waitUntil: 'domcontentloaded' });
await page.locator('main .report-content').waitFor({ state: 'visible', timeout: 30_000 });
await page.screenshot({ path: 'report.png', fullPage: true });

Use a selector that represents the content you need, not a generic element that appears before the page is populated. If images load lazily as the user scrolls, a full-page screenshot may not trigger every site’s lazy-loading behavior. For those sites, use the page’s own readiness behavior or deliberately scroll through the relevant content before capture, then confirm the resulting image.

Output format and screenshot options

BrowserCat’s Playwright cheatsheet documents PNG and JPEG screenshots, JPEG quality, transparency, scaling, animation, and caret behavior. Common choices include:

Option	Use	Notes
path: 'page.png'	Save the output to a file	Choose a matching extension for the requested image type.
type: 'jpeg'	Produce JPEG bytes	JPEG is lossy and does not preserve transparency.
quality: 80	Set JPEG quality	Quality applies to JPEG output; choose a value for the visual fidelity and file size you need.
omitBackground: true	Capture a transparent PNG background	Useful for compositing; use PNG when transparency matters.
scale: 'css'	Scale output according to CSS pixels	Playwright also supports device-scale output; pick based on downstream dimensions and file size.
animations: 'disabled'	Reduce animation-related differences	Relevant to repeatable captures; it changes animation handling during the shot.
caret: 'hide'	Hide the text caret	Useful when capturing pages with focused text inputs.

Example JPEG file:

await page.screenshot({
  path: 'page.jpg',
  type: 'jpeg',
  quality: 80,
  fullPage: true,
});

Check the current BrowserCat Playwright cheatsheet for exact supported screenshot options and defaults before relying on a less common setting.

4. Capture with Python, cURL, or Node.js

Python with Playwright

BrowserCat’s Playwright guide includes a Python connection pattern. Install the Python package and browser driver support required by your Playwright version, then run this asynchronous script:

import asyncio
import os
from playwright.async_api import async_playwright

async def main():
    api_key = os.environ.get("BROWSERCAT_API_KEY")
    if not api_key:
        raise RuntimeError("Set BROWSERCAT_API_KEY before running this script.")

    async with async_playwright() as p:
        browser = await p.chromium.connect(
            "wss://api.browsercat.com/connect",
            headers={"Api-Key": api_key},
        )
        try:
            page = await browser.new_page()
            await page.goto("https://example.com", wait_until="load", timeout=60_000)
            await page.screenshot(path="page.png", full_page=True)
            print("Saved page.png")
        finally:
            await browser.close()

asyncio.run(main())

Node.js with BrowserCat

The runnable Node.js example is the same remote Playwright flow used above: connect with the WebSocket endpoint and API key header, navigate, then call page.screenshot({ path, fullPage: true }). The precise code is in section 2.

Why cURL is not the BrowserCat capture interface

The documented BrowserCat flow is a WebSocket connection used by Playwright, followed by a Playwright page method. It is not a documented HTTP screenshot endpoint, so a cURL GET request to the connection URL is not an equivalent way to take the screenshot. Use Playwright for BrowserCat captures.

5. Full-page image or focused element capture?

A full-page screenshot is useful when the complete document is the artifact: for example, a page archive, a design review, or a page-level visual check. It can be brittle for visual regression because unrelated changes anywhere in the long image may alter the comparison. BrowserCat’s visual-testing guide describes whole-page snapshot tradeoffs and element snapshots.

If you only need a component, capture that locator instead:

const chart = page.locator('[data-testid="revenue-chart"]');
await chart.screenshot({ path: 'revenue-chart.png' });

An element screenshot focuses the artifact on one component and excludes unrelated page regions. It requires locating the element and may need scrolling or waiting until it is visible. See BrowserCat’s visual-testing guide.

6. Troubleshooting

Symptom	Likely cause	Fix
WebSocket connection fails or closes immediately	Missing/invalid API key, blocked outbound WebSocket traffic, or an incorrect endpoint.	Use wss://api.browsercat.com/connect, send the key in the Api-Key header, verify the key, and allow outbound secure WebSocket connections.
Navigation times out	The destination is slow, unreachable from the hosted browser, or never reaches the selected lifecycle state.	Check the URL and accessibility, increase the navigation timeout only when justified, or use a more appropriate readiness condition and a page-specific selector.
Screenshot is blank or incomplete	The app rendered after the capture, a selector appeared before its data, or lazy content has not loaded.	Wait for a stable app signal or the required visible element. Scroll when the target site loads content on scroll, then capture.
Output file is missing	The script failed before the screenshot call, used a different working directory, or the path is not writable.	Log the absolute output path, create the destination directory, and ensure the process can write there.
JPEG option is rejected or quality has no effect	The chosen option may not apply to the selected format; quality is meaningful for JPEG.	Set type: 'jpeg' and a matching .jpg path when using quality; use PNG for transparency.
Very tall pages take a long time or produce large files	The browser must render and encode a large document image.	Capture only the needed region when possible, choose JPEG when transparency is unnecessary, and avoid repeating identical captures more than needed.
Visual comparison fails after unrelated page edits	A full-document baseline includes every captured region.	Use a component locator screenshot for tests that validate only one component, or update the baseline when the page-level change is intentional.

7. Performance, reliability, and cost considerations

• Page height drives work. Full-page output must represent the entire document, so tall pages can take longer to render and encode and can create larger files than viewport or element captures.
• Wait for the right signal. Waiting longer than necessary increases latency; capturing too early creates incomplete output. Prefer a page-specific readiness marker when available.
• Close browser sessions. Use a finally block so errors still close the remote browser connection. For batches, bound concurrency to avoid overwhelming your own process or target sites.
• Handle retries carefully. Retry transient connection or navigation failures with a limit and backoff. Do not retry persistent authentication failures or a destination that predictably blocks the browser.
• Protect the credential. Do not put API keys in client-side code, screenshots, logs, or public repositories.
• Cost depends on BrowserCat account terms. The research sources do not provide a price or billing unit for this capture, so check BrowserCat’s account and billing information before estimating production costs.

Or skip the browser setup

If your goal is simply a clean image or PDF from a URL, ScreenshotNeo offers a one-request screenshot API and an MCP server for AI agents. Its API accepts a URL and returns PNG, JPEG, WebP, or PDF output. See the ScreenshotNeo API documentation for request parameters and configuration.

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

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture, and those cleanup steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; responses identify the page verdict and billing status in headers. Its MCP server includes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

Create a free ScreenshotNeo account and get 1,000 screenshots a month with no card.

FAQ

Does BrowserCat expose a screenshot REST API?

The reviewed BrowserCat documentation describes a WebSocket browser connection and Playwright screenshot calls. It does not document a dedicated screenshot REST endpoint.

Does this run Firefox or WebKit?

The reviewed browser documentation describes Chromium-based sessions; Firefox and WebKit are listed as coming soon. Recheck BrowserCat’s browser documentation for current support before choosing a browser engine.

Does a full-page screenshot test whether a page matches a baseline?

No. The screenshot call creates an image. A visual regression test additionally compares that image with a baseline.

Can I use a full-page screenshot for a very tall page?

Yes, but the image can be large and costly to process downstream. If only one region matters, capture an element instead.

Sources: BrowserCat Playwright connection guide, Playwright cheatsheet, Browser configuration and browser type, Visual testing guide.