Skip to main content

​
Overview

As your number of sessions grows, attaching a customizable label to your sessions helps you organize and access them based on your specific needs. For this, we created Session Metadata. Session metadata can be attached to a session and later be queried as part of our List Sessions API.

​
Why Use Metadata?

Consider running automated tests across multiple browser sessions. Without metadata, you’d 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. Each of these are possible with metadata.

​
Structure

Session metadata is a simple but flexible structure:
  • All metadata is a customizable JSON object
  • Your JSON object must be under 512 characters
  • Data is organized in a nested structure using fields (no arrays supported yet)
  • Only string values are supported for querying (convert numbers and booleans to strings)
  • Metadata persists throughout the entire session lifecycle
Here’s what a typical metadata structure looks like: 
{
  "env": "staging"
}
A more extensive, nested object might look like: 
{
  "run": {
    "id": "run-abc-123"
  },
  "env": "staging",
  "team": "platform"
}

​
Attach Metadata to a Session

Pass the userMetadata parameter when creating a session via the Create Session endpoint. This metadata can be any JSON-serializable object. Below is an example that attaches {"env": "staging"} to a session. 
import Browserbase from "@browserbasehq/sdk";

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

const session = await bb.sessions.create({
  projectId: process.env["BROWSERBASE_PROJECT_ID"]!,
  userMetadata: {
    env: "staging",
  },
});
console.log("Session URL: https://browserbase.com/sessions/" + session.id);

​
Query Sessions by Metadata

Pass a query string to the q parameter in List Sessions to filter sessions by metadata. The query string format is always user_metadata['path']['to']['field']:'value'. Below is an example that finds all sessions with {"env": "staging"}. 
import Browserbase from "@browserbasehq/sdk";

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

const query = "user_metadata['env']:'staging'";
const sessions = await bb.sessions.list({ q: query });
console.log(sessions);
If no sessions match, the API returns an empty list [].

​
Best Practices

Use descriptive, consistent naming and keep your metadata structure shallow and intuitive. Tip: Need to query numbers or booleans? Convert them to strings: 
{
  "priority": "5",
  "active": "true"
}

​
Limitations

  • JSON object must be under 512 characters (think JSON.stringify and measuring the resulting length)
  • Only field queries are supported (no array querying)
  • Only string equality checks are available
  • Only the user_metadata base is supported