​
Overview

As your number of sessions grows, attaching metadata helps to organize your sessions based on your application’s specific needs.

Our List Sessions endpoint supports filtering sessions by status, which is helpful but not highly configurable. Session metadata allows you to attach arbitrary JSON data to sessions, which then gives you additional flexibility when querying sessions.

​
Creating a Session with Metadata

Metadata is attached to a session when hitting our Create Session endpoint. This metadata can be any JSON-serializable object.

This metadata is attached to the stored session object and can be queried against using the List Sessions endpoint.

Below is an example for attaching an order status to a created session. This will attach the object {"order": {"status": "shipped"}} to the created session.

import Browserbase from "@browserbasehq/sdk";

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

async function createSessionWithMetadata() {
  const session = await bb.sessions.create({
    projectId: process.env["BROWSERBASE_PROJECT_ID"]!,
    userMetadata: {
      key: "value",
      key2: {
        key2A: "value2A",
        key2B: "value2B",
      },
    },
  });
  return session;
}

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

The size of the stored JSON object is limited to 512 characters. We measure this by converting your object into a JSON string (think JSON.stringify) and measuring the length of the resulting string.

​
Querying Sessions by Session Metadata

Querying using session metadata is done via the q query parameter on the List Sessions endpoint.

Let’s use the example object {"order": {"status": "shipped"}} from the previous section. To query for all sessions with an order of status "shipped", you can use the following query:

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

This query contains the following components:

  • user_metadata is known as the “base” of the query. Currently we only support the user_metadata base, although we’re working to support more querying bases in the future. Stay tuned!

  • ['order']['path'] is known as the “path” of the query. The path is used to drill into nested fields in the stored metadata object. In this case, we’re looking for an object with keys in the shape { "order": { "status" }}.

  • 'shipped' is known as the “value” of the query. This is separated from the base and the path of the query with a : character. The “value” field of the query is used to check strict equality of the value specified by the “path” of the query. In our case, we’re looking for an object with the exact shape { "order": { "status": "shipped" }}.

Note that we need to URL encode the query string to ensure that it’s properly parsed by the API.

  • %5B is the URL encoded version of [

  • %5D is the URL encoded version of ]

  • %3A is the URL encoded version of :

In JavaScript, you can use encodeURIComponent("user_metadata['order']['status']:'shipped'") to encode the query string.

Below is an example of how to use this query.

import Browserbase from "@browserbasehq/sdk";

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

async function listSessionsWithMetadata(query: string) {
  const sessions = await bb.sessions.list({
      q: query,
  });
  return sessions;
}

const query = "user_metadata['key']:'value'";
const sessions = await listSessionsWithMetadata(query);
console.log(sessions);

This will return a list of all sessions with attached metadata in the form {"order": {"status": "shipped"}}. If the query doesn’t match any sessions, the API will respond with an empty list [].

Currently we only support querying by fields (no arrays) and checking value equality of string (no numbers or booleans). A quick workaround for this is to convert numbers and booleans into strings and query normally.

Was this page helpful?

Browser ExtensionsImproving Performance