Using a Browser Session

​

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:

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

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

import os
from browserbase import Browserbase

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

# Create a session
session = bb.sessions.create(
    project_id=os.environ["BROWSERBASE_PROJECT_ID"]
)

# Connect and automate
browser = bb.connect(session.id)
page = browser.new_page()

​

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:

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

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

page = browser.new_page()  # 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.

​

Browserbase Features

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

​

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.