> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browserbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Labels

> Organize sessions with custom Labels

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](https://mintcdn.com/browserbase/mCVE8XDuHTHt1lhD/images/session-labels/sessions-table.png?fit=max\&auto=format\&n=mCVE8XDuHTHt1lhD\&q=85\&s=ca76485ca0a6b1a677d8ed6d423b0a1b)

## Create Labels

### In the dashboard

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](https://mintcdn.com/browserbase/mCVE8XDuHTHt1lhD/images/session-labels/create-label.png?fit=max\&auto=format\&n=mCVE8XDuHTHt1lhD\&q=85\&s=350bcbc2ebb9a586d65b3ebfc60718b2)

### Using the API

The easiest way to create Labels is to pass their names when
[creating a session](https://docs.browserbase.com/reference/api/create-a-session.md). Browserbase reuses existing
Labels and creates missing ones:

```bash cURL theme={null}
curl --request POST 'https://api.browserbase.com/v1/sessions' \
  --header "X-BB-API-Key: $BROWSERBASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"labels":["Production","Checkout"]}'
```

Label assignment runs in the background and does not delay or fail session
creation. Read the session later to inspect its Labels.

> [!WARNING]
>
> A delayed initial assignment can overwrite an immediate replacement or clear.
> For deterministic initialization, omit Labels during creation and use
> [Set Session Labels](https://docs.browserbase.com/reference/api/set-session-labels.md) afterward.

You can also [create a Label](https://docs.browserbase.com/reference/api/create-a-label.md) without creating a session:

```bash cURL theme={null}
curl --request POST 'https://api.browserbase.com/v1/labels' \
  --header "X-BB-API-Key: $BROWSERBASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Production"}'
```

Save the returned `id` to rename or delete the Label later.

> [!NOTE]
>
> 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

### In the dashboard

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](https://mintcdn.com/browserbase/mCVE8XDuHTHt1lhD/images/session-labels/edit-session-labels.png?fit=max\&auto=format\&n=mCVE8XDuHTHt1lhD\&q=85\&s=f79f175ef36079367b7e35703815f97a)

### Using the API

Call [Set Session Labels](https://docs.browserbase.com/reference/api/set-session-labels.md) with the complete set
of Labels you want on the session:

```bash cURL theme={null}
curl --request PUT "https://api.browserbase.com/v1/sessions/$SESSION_ID/labels" \
  --header "X-BB-API-Key: $BROWSERBASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"labels":["Production","Checkout"]}'
```

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.

## Filter sessions by Labels in the dashboard

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](https://mintcdn.com/browserbase/mCVE8XDuHTHt1lhD/images/session-labels/filter-by-labels.png?fit=max\&auto=format\&n=mCVE8XDuHTHt1lhD\&q=85\&s=c849bf26c5e338e6f57be4931f93c560)

## Read assigned Labels

[Get a Session](https://docs.browserbase.com/reference/api/get-a-session.md) omits Labels by default. Add
`includeLabels=true` to request the assigned Label IDs and current names:

```bash cURL theme={null}
curl "https://api.browserbase.com/v1/sessions/$SESSION_ID?includeLabels=true" \
  --header "X-BB-API-Key: $BROWSERBASE_API_KEY"
```

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

### In the dashboard

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](https://mintcdn.com/browserbase/mCVE8XDuHTHt1lhD/images/session-labels/rename-label.png?fit=max\&auto=format\&n=mCVE8XDuHTHt1lhD\&q=85\&s=30922c50705d106cf6f2d89f90c2bee0)

### Using the API

Call [Update a Label](https://docs.browserbase.com/reference/api/update-a-label.md) with its catalog ID and a new
name. The ID and session assignments stay the same.

```bash cURL theme={null}
curl --request PATCH "https://api.browserbase.com/v1/labels/$LABEL_ID" \
  --header "X-BB-API-Key: $BROWSERBASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"name":"Production checkout"}'
```

Call [Delete a Label](https://docs.browserbase.com/reference/api/delete-a-label.md) to remove it from the active
catalog and session reads:

```bash cURL theme={null}
curl --request DELETE "https://api.browserbase.com/v1/labels/$LABEL_ID" \
  --header "X-BB-API-Key: $BROWSERBASE_API_KEY"
```

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.

## Related guides

> [card] [Session metadata](https://docs.browserbase.com/platform/browser/core-features/session-metadata.md)
>
> Attach custom data to sessions and query it later.

> [card] [Browser observability](https://docs.browserbase.com/platform/browser/observability/observability.md)
>
> Inspect browser activity and diagnose failed runs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.