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.

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

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

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

  • 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