Long Running Sessions

How are sessions terminated?

By default, Browserbase sessions automatically terminate in two scenarios:

1. When a developer disconnects from the session
2. When the session reaches its default timeout period

This behavior is designed to optimize session management and resource utilization. However, in certain scenarios, you may need to maintain a session for an extended period.

We introduced session keep alive and custom timeout to address this need.

Property	Description
Keep Alive	Allowing you to reconnect to the same session after a disconnect
Custom Timeout	Extending the lifetime of a session beyond its default timeout period

Session keep alive is available on the Startup and Scale plans.

Why keep sessions alive?

Custom timeouts and session keep alive supports a broad spectrum of use cases. Key benefits include:

• Avoid interrupting long-running tasks and workflows.
• Connect, disconnect, and reconnect to the same session.
• Keep working with a session without worrying about it timing out.
• Reusing existing sessions is more performant than creating new ones.

Using Keep Alive

Let’s walk through an example of how to keep a session alive, a way to make your sessions more efficient in terms of time and cost.

Here, we have a script that runs a simple search on Google.

import browserbase from "browserbase";

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

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

// Default timeout on Browserbase is set to 1 minute on Browserbase

After the script is past the default timeout, we’ll see a TimeoutError: Timeout _____ms exceeded

In order to keep the session alive, we can use the keepAlive property.

const session = await bb.sessions.create({
  projectId: process.env.BROWSERBASE_PROJECT_ID!,
  keepAlive: true,
});

That way, next time we run the script, we’ll be able to reconnect to the same session after a disconnect.

This enables us to reuse the same session for multiple runs, saving time and cost.

Session Timeouts

Browserbase has a project wide settings for session timeout.

We can change to session timeout project wide to a different value in the toggle.

Custom session timeout

We can also set a custom timeout for a created session through code.

If you’d like to set a custom timeout that isn’t shown in the toggle, you can set a custom timeout in the createSession function.

To set a custom timeout for your session, specify the timeout option in the API request body or with the SDK.

• Node.js
• Python

SDK

import Browserbase from "browserbase";

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

const bb = new Browserbase({
  apiKey: BROWSERBASE_API_KEY,
});

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

Here the timeout has been set to 3600 seconds (1 hour), overriding the default. That means that unless explicitly closed beforehand, the session will continue running for an hour before terminating. At disconnect, it will end.

The maximum duration of a session is 6 hours. Once a session times out, it can no longer be used.

Setting a custom timeout won’t keep the session alive after disconnecting. To allow reconnecting to a session after disconnecting, it needs to be configured for keep alive.

Keeping sessions alive across disconnects

Browserbase offers a keepAlive feature to keep sessions alive across disconnects, allowing you to continue using it as long as needed. Setting keepAlive to true will keep the session available for later use:

• Node.js
• Python

SDK

import Browserbase from "browserbase";

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

const bb = new Browserbase({
  apiKey: BROWSERBASE_API_KEY,
});

// async function that creates a session with keepAlive
(async () => {
  const session = await bb.sessions.create({
    projectId: BROWSERBASE_PROJECT_ID,
    keepAlive: true,
  });
})();

You can reconnect to the keep alive session using the same connection URL as the original session.

Stopping a keep alive session

In order to stop the session, use the Browserbase API or the SDK as shown here:

• Node.js
• Python

SDK

import Browserbase from "browserbase";

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

const bb = new Browserbase({
  apiKey: BROWSERBASE_API_KEY,
});

// Create a session with keep alive set.
// Then, end it by closing it.
(async () => {
  const session = await bb.sessions.create({
    keepAlive: true,
    projectId: BROWSERBASE_PROJECT_ID,
  });

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

We recommend that you stop your keep alive sessions explicitly when no longer needed. They will time out eventually, but you may be charged for the unneeded browser minutes used.