Using a Browser Session

Learn how to connect to and interact with browser sessions

Connecting to a Session

Once you create a session, you’ll receive a connection URL that you can use with your preferred automation framework. Here’s how to connect using our supported frameworks:

• Node.js
• Python

Stagehand

import { Browserbase } from "@browserbasehq/sdk";

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

// Create a session
const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID
});

// Connect and automate
const browser = await bb.connect(session.id);

Connection Best Practices

1. Connection Timeout - You have 5 minutes to connect to a newly created session before it terminates. To prevent timeouts:

   • Connect promptly after creation
   • Enable keep alive for sessions that need to persist
   • Use the connection URL immediately after receiving it

2. Use Default Context - Always use the default context and page when possible to ensure proper functionality of stealth features:

• Node.js
• Python

Stagehand

const page = await browser.newPage(); // Uses default context automatically

Controlling the Browser

Once connected, use your preferred framework’s APIs to control the browser. Each framework has its own methods for navigation, interaction, and automation.

Stagehand

Build reliable browser automation with AI-powered element selection and self-healing scripts

Playwright

Create fast, reliable end-to-end tests with built-in auto-waiting and mobile emulation

Puppeteer

Headless Chrome automation with a lightweight API and strong DevTools integration

Selenium

Industry-standard testing framework supporting all major browsers and programming languages

Browserbase Features

When running browsers in the cloud, certain operations require special handling through our APIs:

File Downloads

Securely retrieve files from your cloud browser session

Screenshots

Capture high-quality browser screenshots with custom settings

PDF Generation

Create PDFs with advanced formatting options

File Upload

Transfer files directly to your browser session

Live View

The Live View feature gives you real-time visibility into your browser sessions through two powerful interfaces:

Session Inspector

The Session Inspector provides real-time debugging capabilities:

Monitor your session’s activity with:

• Live browser state and interactions
• Real-time network requests and responses
• Console output and error tracking
• Performance metrics and resource usage
• Session recording and replay

Embedded View

Integrate the Live View directly into your application to show your users their automated browser sessions in real-time. The Live View enables remote control over the browser, unlocking human-in-the-loop possibilities to handle authentication, captcha, or unexpected errors.

Ending Your Session

While Browserbase automatically handles session termination when you disconnect, understanding how sessions end is important.

For more details about session termination, timeouts, and best practices for managing session lifecycle, see Manage a Browser Session.