Reuse cookies, authentication, and cached data across browser sessions.
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:
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.
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.
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.
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.
Use persist: true if you want to save updates to your context for future use.
Setting persist: false prevents changes from being saved to the context. This is not recommended in most cases, but it can be useful when:
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:
Deleting a context is permanent and cannot be undone. Make sure you no longer need the context before deleting it.
Once you set up contexts, follow our authentication guide to easily log into websites.