By default, Browserbase sessions automatically terminate in two scenarios:
- When a session disconnects
- When the session reaches its timeout
This behavior optimizes resource utilization and session management, but you may need sessions that run longer or survive disconnections.
We introduced session keep alive and custom timeout to address this need.
Two Ways to Extend Sessions
| Feature | Problem it solves |
|---|
| Session Timeouts | ”I need my session to run longer than the default” |
| Keep Alive | ”I need to disconnect and reconnect without ending my session” |
When to use each
Timeouts extend how long a session can run before it automatically terminates. Use this when you have long-running tasks that exceed the default timeout.
Keep Alive allows you to disconnect and reconnect to the same session. Use this when your workflow involves multiple connections, when you need resilience against network issues, or when you want to reuse the same session for multiple runs.
Using both together
If you need a session that both survives disconnects and runs for an extended period, configure both options:
const session = await bb.sessions.create({
projectId: process.env.BROWSERBASE_PROJECT_ID!,
keepAlive: true,
timeout: 3600, // 1 hour
});
Session keep alive is only available on paid 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.
Looking for serverless execution? If you don’t need persistent sessions or reconnection capabilities, consider Functions for on-demand, serverless browser automation. Functions automatically manage session lifecycle and are ideal for webhooks, scheduled tasks, and API endpoints. Keep Alive Sessions
The keepAlive feature allows you to keep sessions alive across disconnects, permitting you to continue using it as long as needed.
Create a Keep Alive Session
Setting keepAlive to true will keep the session available for later use. You can reconnect to the keep alive session using the same connection URL as the original session.
Let’s walk through an example of how to keep a session alive:
const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });
const session = await bb.sessions.create({
projectId: process.env.BROWSERBASE_PROJECT_ID!,
keepAlive: true,
});
bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])
session = bb.sessions.create(
project_id=BROWSERBASE_PROJECT_ID,
keep_alive=True
)
Stop a Keep Alive Session
In order to stop the session, use the Browserbase API or the SDK as shown here:
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,
});
})();
from browserbase import Browserbase
import os
# Initialize the SDK
BROWSERBASE_API_KEY = os.environ["BROWSERBASE_API_KEY"]
BROWSERBASE_PROJECT_ID = os.environ["BROWSERBASE_PROJECT_ID"]
bb = Browserbase(api_key=BROWSERBASE_API_KEY)
# Create a session with keep alive set
session = bb.sessions.create(keep_alive=True, project_id=BROWSERBASE_PROJECT_ID)
# Manually complete the session to end it
bb.sessions.update(session.id, status="REQUEST_RELEASE", project_id=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.
Session Timeouts
After the script is past the default timeout, we’ll see a TimeoutError: Timeout _____ms exceeded
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.
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,
});
})();
from browserbase import Browserbase
import os
BROWSERBASE_API_KEY = os.environ["BROWSERBASE_API_KEY"]
BROWSERBASE_PROJECT_ID = os.environ["BROWSERBASE_PROJECT_ID"]
bb = Browserbase(
api_key=BROWSERBASE_API_KEY,
)
# Creates a session with a timeout of 3600 seconds
session = bb.sessions.create(
project_id=BROWSERBASE_PROJECT_ID,
api_timeout=3600
)
The maximum duration of a session is 6 hours. Once a session times out, it can
no longer be used.
