Using Session Metadata

​

What is Session Metadata?

Session metadata is a customizable label for your browser sessions. While Browserbase already lets you filter sessions by their status, metadata takes this further by allowing you to attach your own JSON data to sessions.

​

Why Use Session Metadata?

Consider the use case where you’re running automated tests across multiple browser sessions. Without metadata, you might struggle to track which session belongs to which test run. With metadata, you can attach a “run ID” to each session and easily query them later. Similarly, you might want to track the status of downloads or associate sessions with specific projects or teams.

​

Technical Implementation

​

Structure and Limitations

Metadata in Browserbase follows a simple yet powerful structure:

• Your JSON object must be under 512 characters

• Data is organized in a nested structure using fields (no arrays supported yet)

• Currently supports string values for comparison (numbers and booleans should be converted to strings)

• Metadata persists throughout the entire session lifecycle - if you restart your session, your metadata stays intact

Here’s what a typical metadata structure looks like:

{
  "order": {
    "status": "shipped"
  }
}

Check out our Session Metadata documentation for step-by-step examples.

​

Querying Your Metadata

The query syntax follows a predictable pattern:

user_metadata['path']['to']['field']:'value'

For example, to find all sessions with shipped orders:

user_metadata['order']['status']:'shipped'

​

Best Practices

As always, metadata is cleaner with descriptive & consistent naming and a shallow and intuitive structure.

​

Current Limitations and Workarounds

While the current implementation is robust, there are some limitations:

• Only field queries are supported (no array querying)

• Only string equality checks are available

• Only the user_metadata base is supported

Pro tip: Need to query numbers or booleans? Convert them to strings in your metadata:

{
  "priority": "5",
  "active": "true"
}

See the full documentation here.