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
});
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:
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:
- Connect to it using your preferred automation framework - see Using a Browser Session
- Monitor it through the Session Inspector
- End it manually or let it timeout - see Manage a Browser Session
Responses are generated using AI and may contain mistakes.