> ## 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)

## 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](https://docs.browserbase.com/reference/api/create-a-session.md). Browserbase reuses existing
Labels and creates missing ones:

```typescript Node.js theme={null}
import Browserbase from "@browserbasehq/sdk";

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

const session = await bb.sessions.create({
  labels: ["Production", "Checkout"],
});
console.log(`Session URL: https://browserbase.com/sessions/${session.id}`);
```

```python Python theme={null}
import os

from browserbase import Browserbase

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

session = bb.sessions.create(labels=["Production", "Checkout"])
print(f"Session URL: https://browserbase.com/sessions/{session.id}")
```

```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:

```typescript Node.js theme={null}
const label = await bb.labels.create({ name: "Production" });
console.log(label.id);
```

```python Python theme={null}
label = bb.labels.create(name="Production")
print(label.id)
```

```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

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:

```typescript Node.js theme={null}
const { labels } = await bb.sessions.setLabels(session.id, {
  labels: ["Production", "Checkout"],
});
console.log(labels.map((label) => label.name));
```

```python Python theme={null}
result = bb.sessions.set_labels(session.id, labels=["Production", "Checkout"])
print([label.name for label in result.labels])
```

```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.

```typescript Node.js theme={null}
await bb.sessions.setLabels(session.id, { labels: [] });
```

```python Python theme={null}
bb.sessions.set_labels(session.id, labels=[])
```

### 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:

```typescript Node.js theme={null}
const details = await bb.sessions.retrieve(session.id, { includeLabels: true });
console.log(details.labels);
```

```python Python theme={null}
details = bb.sessions.retrieve(session.id, include_labels=True)
print(details.labels)
```

```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

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.

```typescript Node.js theme={null}
const renamed = await bb.labels.update(label.id, { name: "Production checkout" });
console.log(renamed.name);
```

```python Python theme={null}
renamed = bb.labels.update(label.id, name="Production checkout")
print(renamed.name)
```

```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:

```typescript Node.js theme={null}
await bb.labels.delete(label.id);
```

```python Python theme={null}
bb.labels.delete(label.id)
```

```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.

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

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

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

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

## 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.