Create a Browser Session

Learn how to create and configure browser sessions in Browserbase

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.

Looking for serverless automation? Functions automatically create and manage sessions for you, letting you deploy browser automation as API-invokable functions without manual session management.

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.

Node.js

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

Python

import os
from browserbase import Browserbase

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])
session = bb.sessions.create(
    project_id=os.environ["BROWSERBASE_PROJECT_ID"],
    # Add configuration options here
)

cURL

curl --request POST \
  --url "https://api.browserbase.com/v1/sessions" \
  --header "Content-Type: application/json" \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY" \
  --data '{
    "projectId": "'$BROWSERBASE_PROJECT_ID'",
    // Add configuration options here
  }'

Configuration Options

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

• Create Session API Reference
• Node.js SDK Reference
• Python SDK Reference

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.
• 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:

  • Automatic 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