Timeout

By default, Browserbase sessions have a timeout period after which they automatically terminate, which prevents sessions from running forever unexpectedly. You can extend this duration either project-wide or per-session. The session still ends when it reaches its timeout.

The maximum session duration is 6 hours. When a session times out, you’ll see a TimeoutError: Timeout _____ms exceeded.

Project-wide timeout

You can change the default session timeout for all sessions in your project through the dashboard settings.

Per-session timeout

Set timeout in the HTTP request body, or api_timeout in the Node.js and Python SDKs, to specify the session duration in seconds. The SDK request option timeout controls how long the client waits for an API response; it does not set the browser session duration. This is useful when different sessions need different timeouts, or when you need more granular control than the dashboard toggle provides.

The examples below set timeout to 3600 seconds (1 hour), overriding the project default. Unless explicitly closed beforehand, the session continues running for an hour before terminating. At disconnect, it ends.

Node.js
Python

import Browserbase from "@browserbasehq/sdk";

const bb = new Browserbase({
  apiKey: process.env.BROWSERBASE_API_KEY!,
});

// Creates a session with a timeout of 3600 seconds (1 hour)
const session = await bb.sessions.create({
  api_timeout: 3600,
});

const options = {
  method: "POST",
  headers: {
    "X-BB-API-Key": "<your-api-key>",
    "Content-Type": "application/json",
  },
  body: '{"timeout": 3600}',
};

fetch("https://api.browserbase.com/v1/sessions", options)
  .then((response) => response.json())
  .then((response) => console.log(response))
  .catch((err) => console.error(err));

from browserbase import Browserbase
import os

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

# Creates a session with a timeout of 3600 seconds (1 hour)
session = bb.sessions.create(api_timeout=3600)

import os
import requests

headers = {
    "x-bb-api-key": os.environ["BROWSERBASE_API_KEY"],
}
json = {
    "timeout": 3600,
}

response = requests.post(
    "https://api.browserbase.com/v1/sessions", json=json, headers=headers
)

response.raise_for_status()
print(response.json())

Timeouts and keep alive

Setting a custom timeout extends how long a session can run, but the session still terminates when you disconnect. If you need to disconnect and reconnect to the same session, use Keep Alive instead. For sessions that need both extended duration and reconnection support, configure both options:

Node.js

const session = await bb.sessions.create({
  keepAlive: true,
  api_timeout: 3600, // 1 hour
});

Keep alive

Learn how to keep sessions alive across disconnects.

Manage browser sessions

Monitor session state and release browsers when work finishes.

Welcome

Platform

Use cases

Optimization

Account

Project-wide timeout

Per-session timeout

Timeouts and keep alive

Keep alive

Manage browser sessions