Skip to main content
Labels help you organize large batches of sessions. You can freely customize Labels for many purposes, such as separating production from beta, or marking the different models used for sessions, such as gpt6 or opus5.5, or labeling the website workflow, such as verizon.com or comcast.com. You can control the Label catalog per Browserbase project. In the dashboard, Labels are shown next to each session.
Sessions table showing reusable Labels assigned to browser sessions

Manage Labels with the Browserbase SDK or API

Create Labels

The easiest way to create Labels is to pass their names when creating a session. Browserbase reuses existing Labels and creates missing ones:
Label assignment runs in the background and does not delay or fail session creation. Read the session later to inspect its Labels.
A delayed initial assignment can overwrite an immediate replacement or clear. For deterministic initialization, omit Labels during creation and use Set Session Labels afterward.
You can also create a Label without creating a session:
Save the returned id to rename or delete the Label later.
Browserbase trims surrounding Unicode whitespace before validating names. A name must contain 1–128 Unicode characters after trimming and cannot contain NUL. Names are unique within a project, ignoring case. The standalone Create a Label endpoint returns 409 if the name already exists.

Assign or replace a session’s Labels

Call Set Session Labels with the complete set of Labels you want on the session:
Browserbase resolves existing names case-insensitively and creates missing names. The response arrives after the replacement commits and contains the assigned catalog entries in { "labels": [...] }. Each request accepts up to 1,000 names. The project’s catalog allowance may be lower. Assigning existing Labels or clearing assignments does not create catalog entries. Send { "labels": [] } to clear the session’s assignments. Clearing assignments keeps the catalog Labels available for other sessions.

Read assigned Labels

Get a Session omits Labels by default. Add includeLabels=true to request the assigned Label IDs and current names:
The response includes labels: [{ id, name }], or labels: [] when the session has no assignments. Omitting includeLabels or setting it to false skips the Label lookup and omits the field.

Rename or delete a Label

Call Update a Label with its catalog ID and a new name. The ID and session assignments stay the same.
Call Delete a Label to remove it from the active catalog and session reads:
Deletion returns 204, preserves sessions, and also succeeds when the Label is already absent. It frees active catalog capacity. Reusing the same name later creates a new catalog entry; it does not restore the old assignments.

Handle errors

  • 400: invalid Label names, request shape, or identifiers.
  • 401: missing or invalid API credentials.
  • 404: the requested session or Label is not in the authenticated project.
  • 409: a catalog Label with the requested name already exists.
  • 422: creating new catalog entries would exceed the project’s allowance. Reuse existing Labels or delete unused catalog Labels before trying again.
  • 429: your requests exceed the API rate limit.
Retry unexpected server failures according to your application’s retry policy. A failed session read does not mean the session has no Labels.

Manage Labels in the dashboard

Create a Label

On the Sessions page, click the tag icon in a session’s Labels column. Type a new name in Search or create, then click Create “my-new-label”. This creates the Label and assigns it to that session.
Creating a new Label from a session's Label picker

Assign or remove a session’s Labels

Click the tag icon in the session’s Labels column. Search for a Label, then check it to assign it or uncheck it to remove the assignment. Changes save automatically; removing an assignment keeps the Label available for other sessions.
Editing a session's Label assignments with the Label picker

Filter sessions by Labels

On the Sessions page, click + in the filter bar, choose Labels, and select the Labels to filter by. Sessions must have all selected Labels to match. Use the search field to find a Label. Click the filter’s × to remove it, or Clear filters to reset all filters.
Filtering the sessions table by Labels in the dashboard

Rename a Label

Click the tag icon in a session’s Labels column, then open the Label’s … menu and choose Rename. Enter the new name and press Enter or click the checkmark to save. Renaming updates the Label across all sessions that use it.
Opening the Label menu to rename a Label in the dashboard

Session metadata

Attach custom data to sessions and query it later.

Browser observability

Inspect browser activity and diagnose failed runs.