By default, browser sessions end when they time out or when you disconnect, whichever comes first. By specifying custom session timeouts and by using the session keep alive feature, you can keep your session running as long as necessary to meet your app’s requirements.

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.

Your web automation framework, such as Playwright, Puppeteer, or Selenium, is responsible for disconnecting and reconnecting to browser sessions.

​
How it works

These examples illustrate using the Sessions API or the SDK to create a basic session:

For these examples, make sure to set your BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID environment variables. To get your API key and project ID, refer to the Settings page in your Dashboard as described in the Start your first Session Quickstart.

This creates a browser session with the default timeout for your project. Now, let’s take a look at creating sessions with custom timeouts.

​
Session timeouts

Sessions normally end when disconnecting or by timing out, whichever comes first. There is a default timeout that you can override in two different ways:

  1. Project-wide. Set the default session timeout for your project in the Dashboard:

Any sessions created for this project will take the specified timeout as default.

  1. Per-session. You can specify the timeout at session create time as shown here:

​
Custom session timeout

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

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:

You can reconnect to the keep alive session using the Connect API. Once reconnected, it will perform as usual.

​
Stopping a keep alive session

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

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.

Was this page helpful?

Session RecordingsIntroduction