How to Write Your First Browserbase Automation Script
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.
- Call the sessions endpoint with your project ID and API key; the response contains a session ID and a WebSocket URL.
- Connect with
chromium.connectOverCDP(wsUrl)in Playwright, then usecontext.pages()to get the default page. 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.
