​
Overview

Contexts allow you to persist user data across multiple browser sessions, enabling smoother automation, authentication, and performance optimizations.

By default, each Browserbase session starts with a fresh user data directory, meaning cookies, cache, and session storage are wiped between sessions. With Contexts, you can reuse stored data across sessions, making automation workflows faster, more reliable, and more efficient. Browser cookies are stored in the user data directory.

Contexts are configured by:

  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.

  • Speeding Up Page Loads: Cache assets, API responses, and other browser data to decrease load times.

    Context data can include stored credentials and other sensitive browsing data. Because of this, contexts are uniquely encrypted at rest to ensure security.

​
Creating a Context

To create a context, use the Create Context API. This will return a unique context ID, which you can pass into new sessions to persist data.

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

async function createContext() {
  const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });
  const context = await bb.contexts.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
  });
  return context;
}

createContext()
  .then((context) => console.log("Context ID:", context.id))
  .catch((error) => console.error("Error:", error));

​
Initializing a Session with Context

After creating a context, you can use it in a new session to reuse cookies, authentication, and cached data. This allows you to create a returning user experience, reducing load times and eliminating the need to log in again.

After a session using a context with persist: true, there will be a brief delay before the updated context state is ready for use in a new session. We recommend temporarily pausing before reusing the same context to ensure all data is properly synchronized. You do not need to wait if you are reusing the same context with persist: false.

Here’s an example of how to use a context in a new session, this example uses the context ID from the previous example.

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

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

async function useContext(contextId: string) {
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
    browserSettings: {
      context: {
        id: contextId,
        persist: true,
      },
    },
  });
  return session;
}

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

const session = useContext(contextId).then((session) => {
  console.log("Session URL: https://browserbase.com/sessions/" + session.id);
});

​
Why set persist: true?

By default, a context loads saved data from previous sessions but does not update it. If you need to store new cookies, authentication tokens, or cached data, you must set persist: true when creating a session. The data will be saved when the session closes.

This ensures that any changes made during the session—such as logging in, saving site preferences, or caching assets—are retained for future sessions instead of being lost when the session ends.

​
When to enable persist: true

Use persist: true if you want to save updates to your context for future use.

  • Persisting Authentication: Saves login credentials and session cookies, so you don’t need to log in again.
  • Retaining User Preferences: Stores UI settings, site preferences, and other local storage changes.
  • Caching Data for Faster Loads: Retains network cache to reduce redundant API calls and speed up automation.
  • Minimizing Captcha & Bot Detection: Preserves cookies and session history to help avoid frequent bot challenges.

​
When to keep persist: false (rare use cases)

Setting persist: false prevents changes from being saved to the context. This is not recommended in most cases, but it can be useful when:

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

​
Deleting Contexts

When you no longer need a context, you can delete it using the Delete Context API. Once deleted, a context cannot be used to create new sessions and any attempts to do so will fail.

Here’s how to delete a context:

  1. Use the Delete Context API with the context ID
  2. The API will return a 204 status code on success
  3. Any subsequent attempts to use this context ID will fail with a 404 error

Deleting a context is permanent and cannot be undone. Make sure you no longer need the context before deleting it.

import axios from "axios";

async function deleteContext(contextId: string) {
  try {
    const response = await axios.delete(
      `https://api.browserbase.com/v1/contexts/${contextId}`,
      {
        headers: {
          "X-BB-API-Key": process.env.BROWSERBASE_API_KEY,
        },
      },
    );
    console.log("Context deleted successfully:", response.status);
  } catch (error) {
    console.error("Error deleting context:", error.response.data);
  }
}
// Use the context ID from the previous examples
const contextId = "<context-id>";
deleteContext(contextId);

Handling Authentication

Once you set up contexts, follow our authentication guide to easily log into websites.