Sessions

​

Overview

In web automation, a browser session in web automation represents a single browser instance, from connection to termination: closure, timeout, or disconnection, running in isolated environments to ensure resource exclusivity, thereby maintaining stability and performance.

These sessions are highly configurable through APIs, allowing for adjustments to settings such as running in a selected geographic region or specifying a keep alive session.

Sessions also support on-the-fly file downloads and can be easily started with automation frameworks like Playwright, Puppeteer, or Selenium, or pre-configured using a Session API, offering flexibility and control for developers.

​

Browser configuration

Sessions run on fast instances with isolated resources (storage, network, memory, and vCPUs).

The viewport, user agents, and header configuration are handled by the fingerprint mechanism.

Downloads are enabled and stored by default, accessible via the API.

​

Sessions

​

Starting a Session

A Session is either created implicitly upon connection (via connectOverCDP() or puppeteer.connect()), or via the Sessions API.

Once created, connect to a Session through a Driver (Playwright, Puppeteer, or Selenium) or via the Session Inspector.

• Node.js
• Python

​

Asynchronous Sessions

You can also create and manage Sessions asynchronously. This is useful if you want to run your automation in an asynchronous environment, such as an asyncio event loop.

Here’s an example using Playwright with async/await:

• Python

import os
from playwright.async_api import async_playwright, Page
import asyncio

# Use environment variable for API key

API_KEY = os.environ.get("BROWSERBASE_API_KEY")

async def run(browser_tab: Page):
    await browser_tab.goto("https://www.sfmoma.org")
    await browser_tab.get_by_role("link", name="Tickets").click()
    print(f"Current URL: {browser_tab.url} | Page title: {await browser_tab.title()}")

async def main():
    async with async_playwright() as playwright:
        browser = await playwright.chromium.connect_over_cdp(
            f"wss://connect.browserbase.com?apiKey={API_KEY}"
        )
        print(
            f"Connected to Browserbase. {browser.browser_type.name} version {browser.version}"
        )
        context = browser.contexts[0]
        browser_tab = context.pages[0]
        await run(browser_tab)

if __name__ == "__main__":
    asyncio.run(main())

​

Session Timeout

Sessions time out when running for longer than the timeout configured in your Project’s Settings:

To keep sessions alive upon disconnections, provide the keepAlive param when creating a new Session and stop the session manually:

• Node.js
• Python

import Browserbase from "browserbase";

const BROWSERBASE_API_KEY = process.env.BROWSERBASE_API_KEY!;
const BROWSERBASE_PROJECT_ID = process.env.BROWSERBASE_PROJECT_ID!;

// Initialize the SDK
const bb = new Browserbase(BROWSERBASE_API_KEY);

// Create a session with `keepAlive` set to `true`
const session = await bb.sessions.create({
  projectId: BROWSERBASE_PROJECT_ID,
  keepAlive: true,
});

// Terminate the session
await bb.sessions.update(session.id, {
  projectId: BROWSERBASE_PROJECT_ID,
  status: "REQUEST_RELEASE",
});

​

Inspecting a Session

You can inspect a completed Session using the Session API or the Session Inspector:

​

Session Concurrency and Rate Limiting

When reaching the session concurrency limit of your plan, any subsequent request to create a new session will return an HTTP 429 error. That means the request was effectively dropped.

You can create sessions again by running fewer concurrent sessions or by closing them explicitly when no longer needed rather than letting them time out.

Since each browser session runs for 1 minute minimum, this also means that you cannot create more than your plan’s session limit within a 60 second sliding window.

For example, if you have a Hobby plan with a limit of 3 concurrent sessions, you can create up to 3 sessions in a 60 second window. If you try to create a 4th session within that window, it will be rate limited and return an HTTP 429 error.