​
Overview

A browser session represents a single browser instance running in the cloud. It’s the fundamental building block of Browserbase, providing an isolated environment for your web automation tasks.

​
Creating a Session

Browser sessions are created through the Sessions API, which gives you full control over configuration and features. After creation, you’ll receive a connection URL to use with your preferred automation framework.

The create session API is rate limited based on your plan’s concurrent session limits. See Concurrency & Rate Limits for details on limits and best practices for handling them.

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

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });
const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  // Add configuration options here
});

​
Configuration Options

When creating a session, you can configure various settings. For complete API details, see:

​
Basic Settings

  • Region - Decrease latency by choosing where your browser runs using one of our browser regions
  • Viewport - Set custom screen dimensions for your browser window. Otherwise, the default viewport varies per session
  • Keep Alive - Enable longer-running sessions that run even after disconnection
  • Recording - Enable/disable session recording (enabled by default)
  • Logging - Enable/disable session logging for debugging (enabled by default)

​
Advanced Features

  • Stealth Mode - Configure anti-bot mitigations:

    • Basic fingerprinting (devices, locales, operating systems)
    • Advanced stealth mode (Scale plan only)
    • Proxy settings
    • Captcha solving (enabled by default)

  • Extensions - Load custom browser extensions to enhance functionality

  • Browser Context - Configure isolated browsing contexts for session persistence

  • User Metadata - Attach custom data for session organization and filtering

​
Next Steps

Once you’ve created a session, you can:

  1. Connect to it using your preferred automation framework - see Using a Browser Session
  2. Monitor it through the Session Inspector
  3. End it manually or let it timeout - see Manage a Browser Session

Was this page helpful?

SeleniumUsing a Browser Session