Sessions
Each Browser run is a Session, controlled through our APIs.
Overview
A 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 viewport size and user agents via fingerprinting.
This customization is crucial for accurately simulating various user behaviors and conducting cross-platform testing.
Sessions also support on-the-fly file downloads and can be easily started with automation tools 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 on the fly, 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.
You must connect to a Session within the timeout supplied during creation or the default timeout of your project.
Session Timeout
Sessions time out when running for longer than the timeout configured in your Project’s Settings:
![](https://mintlify.s3-us-west-1.amazonaws.com/browserbase/images/browser-sessions/timeout.png)
The following code samples require the Browserbase SDK.
To keep sessions alive upon disconnections, provide the keepAlive
param when creating a new Session and stop the session manually:
import { Browserbase } from "@browserbasehq/sdk";
// Initialize the SDK
const browserbase = new Browserbase();
// Create a session with `keepAlive` set to `true`
const session = await browserbase.createSession({
keepAlive: true,
});
// Terminate the session
await browserbase.completeSession(session.id)
We recommend that you release your keep alive sessions manually when no longer needed. They will time out eventually, but you may be charged for the unneeded browser minutes used.
Inspecting a Session
You can inspect a completed Session using the Session API or the Session Inspector:
Action | Session Inspector | Sessions API |
---|---|---|
Access logs | ✅ | Sessions API logs endpoint |
Access ChromeDevTools data (ex: network, DOM events) | ✅ | Sessions API logs endpoint |
Access recording | ✅ | Sessions API recording endpoint |
Retrieve downloaded files | ❌ | Sessions API downloads endpoint |
Session Live View | ❌ | Sessions API Live URLs endpoint |
Access memory and CPUs usage | ✅ | ❌ |
Was this page helpful?