How to Write Your First Browserbase Automation Script

November 21, 2026

Browserbase runs headless Chrome for you. Instead of managing a container, a Chrome version and a captcha-riddled IP, you create a session through an API call, connect Playwright or Puppeteer to it, and drive a browser that lives in their cloud.

That is the whole idea. Everything else is detail, and the details are what this covers.

What does a minimal session look like?

Three steps. Create the session, connect, close.

  1. Call the sessions endpoint with your project ID and API key; the response contains a session ID and a WebSocket URL.
  2. Connect with chromium.connectOverCDP(wsUrl) in Playwright, then use context.pages() to get the default page.
  3. await browser.close() or call the session-complete endpoint when done.

If you skip step three, sessions linger until they time out, and you pay for the time. Wrap the whole thing in a try/finally so a thrown error still closes the session.

How do you see what the browser is doing?

This is the reason to use it. Every session records: a video, network requests, console logs, and a live view URL you can open while the script runs.

Practical value: when a selector fails in the cloud and works locally, the live view or the video shows whether a cookie banner, a redirect or a loading state is in the way. Debugging headless runs blind is where most hours go.

Turn recording off for high-volume production runs once the script is stable; recordings cost storage.

What should you set on the context?

Defaults are fine for a first script. For anything real:

  • Viewport — set it explicitly (1280×800 is a reasonable default), because responsive layouts change which elements exist.
  • Locale and timezone — a US locale on an EU target site changes cookie banners and prices.
  • User agent — the default is a headless marker; set a real one for sites that behave differently.
  • Proxy — optional, per project or per session, region-matched to your target.

Persist cookies between sessions when a workflow needs a login; otherwise every run starts from cold and re-authenticates.

What does it cost?

Pricing is per browser-hour plus plan fees, with a free tier that gives a limited number of hours for development. A fast scrape of twenty pages finishes in under a minute of browser time, so hours accumulate slowly; the cost surprises come from sessions left open and pages that hang on a selector timeout.

Set a session timeout explicitly (five minutes is generous for most scripts) so a hung run cannot bill indefinitely.

Where this approach is wrong

Static pages. If the content is in the initial HTML, a plain HTTP request is ten to a hundred times cheaper and faster. Reaching for a browser out of habit is the most common waste in this category.

Very high volume of simple interactions. Browser-hour pricing adds up; a script you host yourself on your own infrastructure may win above a certain threshold.

Pages that strictly forbid automation. Terms of service still apply; the cloud does not change that.

Who it suits

Developers building scrapers, agents or browser-driven tests who do not want to maintain Chrome infrastructure. Teams with bursty workloads — a hundred sessions today, five tomorrow — who would over-provision a server fleet.

Quick Summary

  • Create a session via API, connect Playwright over CDP, and always close in a finally block.
  • Session recordings and a live view URL make cloud failures debuggable; disable recordings once stable.
  • Set viewport, locale, timezone and a real user agent per context, and persist cookies for logged-in flows.
  • Pricing is per browser-hour with a limited free dev tier; set an explicit session timeout.
  • Skip the browser for static pages — plain HTTP is far cheaper.