Contexts

1. Creating a Context via the Contexts API
2. Passing the Context ID into the Create Sessions API

Why use Contexts?

• Reusing cookies & session data: Maintain login states across multiple sessions without needing to log in repeatedly.
• Preserving authentication: Store and reuse authentication tokens, reducing the need to re-enter credentials.
• Retaining application data: Persist localStorage, IndexedDB, and other site-specific data written by web applications.
• Faster workflows: Skip login flows and re-authentication steps, reducing the total time of your automation runs.

Create a Context

import { Browserbase } from "@browserbasehq/sdk";

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });
const context = await bb.contexts.create({
  name: "my-context",
});

console.log("Context ID:", context.id);

from browserbase import Browserbase
import os

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])
context = bb.contexts.create(name="my-context")

print("Context ID:", context.id)

curl -X POST https://api.browserbase.com/v1/contexts \
  -H "Content-Type: application/json" \
  -H "X-BB-API-Key: $BROWSERBASE_API_KEY" \
  -d '{"name": "my-context"}'

Use a Context

import { Browserbase } from "@browserbasehq/sdk";

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

// Use the context ID from the previous example
const contextId = "<context-id>";

const session = await bb.sessions.create({
  browserSettings: {
    context: {
      id: contextId,
      persist: true,
    },
  },
});

console.log("Session URL: https://browserbase.com/sessions/" + session.id);

from browserbase import Browserbase
import os

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

# Use the context ID from the previous example
context_id = "<context-id>"

session = bb.sessions.create(
    browser_settings={
        "context": {
            "id": context_id,
            "persist": True,
        },
    }
)

print("Session URL: https://browserbase.com/sessions/" + session.id)

Set persist

• Read-only session: If you need to access saved cookies or data without modifying them.
• Prevent session state changes: Avoids overwriting stored login tokens or user data.

Login workflow

1. Create a Context (get a contextId).
2. Start a first Browserbase session with that contextId and persist: true.
3. Log in to a website inside this first session, either manually through the live view feature or programmatically.
4. End this session.
5. Wait a few seconds to ensure that the Context is updated.
6. Start a second Browserbase session (and future sessions) with the same contextId and visit the same website. You should now be signed in automatically without having to repeat the login process.

Login best practices

• Avoid simultaneous logins: Avoid having multiple sessions using the same Context at once. Sites may force a log out.
• One Context per site, per login: Prevent an individual Context from becoming too large, which can slow down your session.

Context expiration

Client-side invalidation

• Explicit deletion: Calling the Delete Context API permanently removes the Context
• Project deletion: If the parent project is deleted, all associated Contexts are removed
• Account changes: Account suspension or deletion will invalidate all Contexts

Application-level invalidation

• Session expiration: Websites may expire authentication cookies after a set period (e.g., 30 days), requiring re-authentication even with a persisted Context
• Password changes: If you change your password on a website, stored session cookies may be invalidated by that website
• Server-side logout: Websites can invalidate sessions server-side (e.g., “log out of all devices”)
• Token revocation: OAuth tokens or API keys stored in cookies may be revoked by the service provider
• Security events: Websites may force re-authentication after detecting suspicious activity

Merge Contexts

Read cookies from the source Contexts

import { browserbase, Stagehand } from "@browserbasehq/stagehand";

const sessionA = await browserbase.connect({
  apiKey: process.env.BROWSERBASE_API_KEY!,
  sessionId: "<session-id-for-context-a>",
});
const sessionB = await browserbase
  .connect({
    apiKey: process.env.BROWSERBASE_API_KEY!,
    sessionId: "<session-id-for-context-b>",
  })
  .catch(async (error) => {
    await sessionA.close();
    throw error;
  });

const [cookiesA, cookiesB] = await Promise.all(
  [sessionA, sessionB].map(async (browser) => {
    await Stagehand.create({ browser });
    return browser.context.cookies();
  }),
).finally(async () => {
  await Promise.all([sessionA.close(), sessionB.close()]);
});

if (!cookiesA.length || !cookiesB.length) {
  throw new Error("Check that both source Contexts contain saved cookies.");
}

Combine the cookie snapshots

const merged = new Map();

for (const cookie of [...cookiesA, ...cookiesB]) {
  const copy = {
    name: cookie.name,
    value: cookie.value,
    domain: cookie.domain,
    path: cookie.path,
    expires: cookie.expires,
    httpOnly: cookie.httpOnly,
    secure: cookie.secure,
    sameSite: cookie.sameSite,
  };
  const key = JSON.stringify([copy.domain.toLowerCase(), copy.path, copy.name]);
  const existing = merged.get(key);
  if (existing && JSON.stringify(existing) !== JSON.stringify(copy)) {
    throw new Error("Conflicting cookies; choose one login before merging.");
  }
  merged.set(key, copy);
}

const cookies = [...merged.values()];

Save to a fresh Context

const sessionC = await browserbase.connect({
  apiKey: process.env.BROWSERBASE_API_KEY!,
  sessionId: "<session-id-for-context-c>",
});
try {
  await Stagehand.create({ browser: sessionC });
  await sessionC.context.addCookies(cookies);
} finally {
  await sessionC.close();
}

Delete a Context

import { Browserbase } from "@browserbasehq/sdk";

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

const contextId = "<context-id>";
await bb.contexts.delete(contextId);

console.log("Context deleted");

from browserbase import Browserbase
import os

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

context_id = "<context-id>"
bb.contexts.delete(context_id)

print("Context deleted")

curl -X DELETE https://api.browserbase.com/v1/contexts/<context-id> \
  -H "X-BB-API-Key: $BROWSERBASE_API_KEY"