diff --git a/content/docs/overview/sessions-api/configuration.mdx b/content/docs/overview/sessions-api/configuration.mdx
index acb5b9c6..a6c6220a 100644
--- a/content/docs/overview/sessions-api/configuration.mdx
+++ b/content/docs/overview/sessions-api/configuration.mdx
@@ -62,6 +62,7 @@ If you know the browser behavior that the task needs, use this table.
| Set the browser window size | `dimensions` | [Browser interface](#browser-interface) |
| Use fullscreen mode | `fullscreen: true` | [Browser interface](#browser-interface) |
| Select the project context | `projectId`, `namespace` | [Project context](#project-context) |
+| Tag the session with your own IDs | `metadata` | [Session Metadata](/overview/sessions-api/session-metadata) |
`useProxy` accepts `true`, `false`, or a configuration object. Properties such as `geolocation` are
part of the `useProxy` object.
diff --git a/content/docs/overview/sessions-api/meta.json b/content/docs/overview/sessions-api/meta.json
index 178be6ba..66fdb43d 100644
--- a/content/docs/overview/sessions-api/meta.json
+++ b/content/docs/overview/sessions-api/meta.json
@@ -7,6 +7,8 @@
"quickstart",
"configuration",
"session-lifecycle",
+ "session-metadata",
+ "session-signals",
"mobile-mode",
"fullscreen-mode",
"dedicated-ips",
diff --git a/content/docs/overview/sessions-api/session-lifecycle.mdx b/content/docs/overview/sessions-api/session-lifecycle.mdx
index 1dc5d413..4fd43bdf 100644
--- a/content/docs/overview/sessions-api/session-lifecycle.mdx
+++ b/content/docs/overview/sessions-api/session-lifecycle.mdx
@@ -176,6 +176,70 @@ print(response.message) # "All sessions released successfully"
+### Why a Session Ended
+
+Every released or failed session has a `releaseReason`. It is `null` while the session is live, and for sessions created before Steel tracked the reason.
+
+
+
+```typescript !! Typescript -wcn
+const session = await client.sessions.retrieve(sessionId);
+
+console.log(session.status, session.releaseReason);
+```
+
+```python !! Python -wcn
+session = client.sessions.retrieve(session_id)
+
+print(session.status, session.release_reason)
+```
+
+
+
+| `releaseReason` | Meaning |
+|---|---|
+| `user_requested` | You released the session through the API or SDK. |
+| `timeout` | The session reached its `timeout`. |
+| `inactivity_timeout` | The session had no activity for its `inactivityTimeout`. |
+| `creation_timeout` | The session did not start in time. |
+| `startup_failed` | Steel could not start the browser. |
+| `browser_closed` | The browser or agent closed itself. This is not a crash. |
+| `browser_crashed` | The browser crashed, or its machine stopped responding. |
+
+### Find Past Sessions
+
+`sessions.list` returns sessions newest first. Filter it by status, release reason, or creation time.
+
+
+
+```typescript !! Typescript -wcn
+for await (const session of client.sessions.list({
+ releaseReason: 'timeout',
+ createdAfter: '2026-11-01T00:00:00Z',
+ createdBefore: '2026-11-02T00:00:00Z',
+})) {
+ console.log(session.id, session.createdAt);
+}
+```
+
+```python !! Python -wcn
+for session in client.sessions.list(
+ release_reason="timeout",
+ created_after="2026-11-01T00:00:00Z",
+ created_before="2026-11-02T00:00:00Z",
+):
+ print(session.id, session.created_at)
+```
+
+
+
+- The list leaves out failed sessions unless you pass `status` or `releaseReason`. Pass `status: 'failed'` to list failed sessions.
+- `releaseReason` leaves out live sessions. Without `status`, it includes failed sessions with that reason.
+- `createdAfter` includes sessions created at that exact time. `createdBefore` does not. Both take ISO 8601 timestamps.
+- `totalCount` comes back only for `status: 'live'` with no metadata, signal, release reason, or date filter. For other lists, follow `nextCursor` until it is `null`. The SDK does this for you.
+
+To filter by your own keys or by what happened during the session, see [Session Metadata](/overview/sessions-api/session-metadata) and [Session Signals](/overview/sessions-api/session-signals).
+
:::callout
type: help
### Need help building with the Sessions API?
@@ -204,4 +268,8 @@ Set `inactivityTimeout` so the session releases itself if your side goes quiet
### How do I end a Steel session before it times out?
Call `client.sessions.release(session.id)` — releasing explicitly is best practice rather than waiting for the timeout. To clean up everything at once, `client.sessions.releaseAll()` releases all active sessions.
+
+### How do I find Steel sessions that failed or timed out?
+
+Call `client.sessions.list({ status: 'failed' })` for failed sessions, or filter by `releaseReason`, such as `timeout` or `browser_crashed`. The default list leaves failed sessions out. Each session's `releaseReason` tells you why it ended.
:::
diff --git a/content/docs/overview/sessions-api/session-metadata.mdx b/content/docs/overview/sessions-api/session-metadata.mdx
new file mode 100644
index 00000000..5213831b
--- /dev/null
+++ b/content/docs/overview/sessions-api/session-metadata.mdx
@@ -0,0 +1,189 @@
+---
+title: Session Metadata
+sidebarTitle: Session Metadata
+description: Attach your own key-value pairs to Steel sessions, change them during or after a run, and find sessions by them later.
+llm: true
+publishedAt: "2026-11-04"
+---
+
+### Overview
+
+Session metadata is a flat set of key-value pairs that you attach to a session. Use it to store your own identifiers, such as a job ID, a customer, or an environment. Steel returns metadata on every session response and shows it on the session page in the dashboard, so don't store secrets in it.
+
+
+
+```typescript !! Typescript -wcn
+import Steel from 'steel-sdk';
+
+const client = new Steel();
+
+const session = await client.sessions.create({
+ metadata: {
+ job_id: 'job-1042',
+ customer: 'acme',
+ attempt: 1,
+ },
+});
+
+console.log(session.metadata);
+```
+
+```python !! Python -wcn
+from steel import Steel
+
+client = Steel()
+
+session = client.sessions.create(
+ metadata={
+ "job_id": "job-1042",
+ "customer": "acme",
+ "attempt": 1,
+ },
+)
+
+print(session.metadata)
+```
+
+
+
+Steel stores every value as a string. Numbers and booleans come back in their string form, so `1` comes back as `"1"`:
+
+```json JSON -wcn
+{
+ "job_id": "job-1042",
+ "customer": "acme",
+ "attempt": "1"
+}
+```
+
+### Update Metadata
+
+`updateMetadata` changes only the keys that you send. Set a key to `null` to remove it. Keys that you leave out keep their values. You can update metadata while the session runs and after it ends.
+
+
+
+```typescript !! Typescript -wcn
+const { metadata } = await client.sessions.updateMetadata(session.id, {
+ metadata: {
+ outcome: 'success',
+ attempt: null,
+ },
+});
+
+console.log(metadata);
+```
+
+```python !! Python -wcn
+result = client.sessions.update_metadata(
+ session.id,
+ metadata={
+ "outcome": "success",
+ "attempt": None,
+ },
+)
+
+print(result.metadata)
+```
+
+
+
+The response contains the merged metadata:
+
+```json JSON -wcn
+{
+ "metadata": {
+ "job_id": "job-1042",
+ "customer": "acme",
+ "outcome": "success"
+ }
+}
+```
+
+Each update is atomic. If two updates change different keys at the same time, Steel keeps both changes.
+
+### Replace Metadata
+
+`replaceMetadata` replaces the whole object. Send an empty object to clear it. If two replacements arrive at the same time, the last one wins.
+
+
+
+```typescript !! Typescript -wcn
+await client.sessions.replaceMetadata(session.id, {
+ metadata: { job_id: 'job-1042', owner: 'data-team' },
+});
+
+await client.sessions.replaceMetadata(session.id, { metadata: {} });
+```
+
+```python !! Python -wcn
+client.sessions.replace_metadata(
+ session.id,
+ metadata={"job_id": "job-1042", "owner": "data-team"},
+)
+
+client.sessions.replace_metadata(session.id, metadata={})
+```
+
+
+
+Use `updateMetadata` unless you want to remove every key that you don't send.
+
+| SDK method | Endpoint | Behavior |
+|---|---|---|
+| `updateMetadata` (`update_metadata` in Python) | `PATCH /v1/sessions/{id}/metadata` | Merges the keys that you send. `null` removes a key. |
+| `replaceMetadata` (`replace_metadata` in Python) | `PUT /v1/sessions/{id}/metadata` | Replaces all keys. `{}` clears the metadata. |
+
+### Find Sessions by Metadata
+
+Pass `metadata` to `sessions.list` to find sessions with matching values. Each value must match the stored string exactly. If you pass several keys, a session must match all of them.
+
+
+
+```typescript !! Typescript -wcn
+for await (const session of client.sessions.list({
+ metadata: { customer: 'acme', job_id: 'job-1042' },
+})) {
+ console.log(session.id, session.status);
+}
+```
+
+```python !! Python -wcn
+for session in client.sessions.list(
+ metadata={"customer": "acme", "job_id": "job-1042"},
+):
+ print(session.id, session.status)
+```
+
+
+
+The SDK fetches every page for you. Over HTTP, send each key in bracket form and follow `nextCursor` until it is `null`:
+
+```bash cURL -wcn
+curl -G https://api.steel.dev/v1/sessions \
+ -H "steel-api-key: $STEEL_API_KEY" \
+ --data-urlencode "metadata[customer]=acme" \
+ --data-urlencode "metadata[job_id]=job-1042"
+```
+
+- Filter values are strings. Pass `attempt: '1'` to match a value that you sent as `1`.
+- The list leaves out failed sessions unless you pass `status` or `releaseReason`. See [Find Past Sessions](/overview/sessions-api/session-lifecycle#find-past-sessions).
+- To find sessions in a job that hit a CAPTCHA or a bot block, add a `signal` filter. See [Session Signals](/overview/sessions-api/session-signals).
+
+### Limits
+
+| Rule | Limit |
+|---|---|
+| Keys | Up to 50 per session |
+| Size | Up to 8 KiB, measured as UTF-8 JSON |
+| Key format | Starts with a letter. Uses only letters, digits, `_`, `.`, and `-`. Up to 64 characters. |
+| Reserved keys | Keys that start with `steel_` |
+| Values | Strings up to 1024 characters, numbers, or booleans |
+| Keys per update | Up to 100 in one `updateMetadata` call |
+
+A request that breaks a rule fails with a `400` error that names the key. An update that would push the merged metadata past a limit fails and leaves the session unchanged.
+
+:::callout
+type: help
+### Need help with session metadata?
+Reach out to us on the #help channel on [Discord](https://discord.gg/steel-dev) or [@steeldotdev](https://twitter.com/steeldotdev).
+:::
diff --git a/content/docs/overview/sessions-api/session-signals.mdx b/content/docs/overview/sessions-api/session-signals.mdx
new file mode 100644
index 00000000..475a92be
--- /dev/null
+++ b/content/docs/overview/sessions-api/session-signals.mdx
@@ -0,0 +1,166 @@
+---
+title: Session Signals
+sidebarTitle: Session Signals
+description: Read the signals Steel records on each session, such as CAPTCHAs, bot blocks, and proxy failures, and find the sessions that hit them.
+llm: true
+publishedAt: "2026-11-04"
+---
+
+### Overview
+
+Signals are labels that Steel adds to a session when it sees certain events during the run, such as a CAPTCHA or a bot block. You don't set signals. To attach your own labels, use [session metadata](/overview/sessions-api/session-metadata).
+
+
+
+```typescript !! Typescript -wcn
+import Steel from 'steel-sdk';
+
+const client = new Steel();
+
+const session = await client.sessions.retrieve(sessionId);
+
+console.log(session.signals);
+```
+
+```python !! Python -wcn
+from steel import Steel
+
+client = Steel()
+
+session = client.sessions.retrieve(session_id)
+
+print(session.signals)
+```
+
+
+
+`signals` is an array of signal names. Sessions in `sessions.list` results carry the same field:
+
+```json JSON -wcn
+["captcha_encountered", "bot_detection_triggered"]
+```
+
+### Available Signals
+
+| Signal | What it means |
+|---|---|
+| `captcha_encountered` | A CAPTCHA was detected during the session. |
+| `bot_detection_triggered` | A page ended on an anti-bot block or challenge that the browser did not get past. |
+| `proxy_connection_failed` | The proxy connection failed or was unreliable. |
+| `session_timeout_exceeded` | The session ended on its timeout or inactivity limit. |
+| `context_restored` | The session restored a previously saved browser context. |
+
+For the exact reason a session ended, read its `releaseReason`. See [Why a Session Ended](/overview/sessions-api/session-lifecycle#why-a-session-ended).
+
+### When Signals Appear
+
+Steel adds signals to a session when the session ends. While the session runs, `signals` is an empty array. Steel fills it in within a few seconds after release.
+
+
+
+```typescript !! Typescript -wcn
+await client.sessions.release(session.id);
+
+await new Promise((resolve) => setTimeout(resolve, 10_000));
+
+const { signals } = await client.sessions.retrieve(session.id);
+```
+
+```python !! Python -wcn
+import time
+
+client.sessions.release(session.id)
+
+time.sleep(10)
+
+signals = client.sessions.retrieve(session.id).signals
+```
+
+
+
+An empty array doesn't prove that nothing happened. Detection uses heuristics and doesn't cover every case. A signal records that Steel saw the event at some point in the session. It doesn't describe the final state of the page.
+
+### Look Up Signal Definitions
+
+`signalCatalog` returns the current signals with a label and a description for each. Use it to show signals in your own UI without hardcoding the list.
+
+
+
+```typescript !! Typescript -wcn
+const catalog = await client.sessions.signalCatalog();
+
+for (const signal of catalog.signals) {
+ console.log(signal.value, signal.label, signal.severity);
+}
+```
+
+```python !! Python -wcn
+catalog = client.sessions.signal_catalog()
+
+for signal in catalog.signals:
+ print(signal.value, signal.label, signal.severity)
+```
+
+
+
+Each entry has a `severity` of `info`, `warning`, `danger`, or `success`. The `semantics` field states the same limits as the section above:
+
+```json JSON -wcn
+{
+ "signals": [
+ {
+ "value": "bot_detection_triggered",
+ "label": "Bot blocked",
+ "description": "A page ended on an anti-bot block or challenge that the browser did not get past",
+ "source": "derived",
+ "severity": "warning"
+ }
+ ],
+ "semantics": "Signals record what was observed at some point during a session, not the current page state. ..."
+}
+```
+
+Steel can add signals over time. Handle signal values that you don't recognize.
+
+### Find Sessions by Signal
+
+Pass `signal` to `sessions.list` to find sessions that carry a signal. If you pass several signals, a session must carry all of them. Combine `signal` with `metadata` to narrow the search to one of your jobs or customers.
+
+
+
+```typescript !! Typescript -wcn
+for await (const session of client.sessions.list({
+ metadata: { job_id: 'job-1042' },
+ signal: ['bot_detection_triggered'],
+})) {
+ console.log(session.id, session.signals);
+}
+```
+
+```python !! Python -wcn
+for session in client.sessions.list(
+ metadata={"job_id": "job-1042"},
+ signal=["bot_detection_triggered"],
+):
+ print(session.id, session.signals)
+```
+
+
+
+Over HTTP, repeat the `signal` parameter for each signal:
+
+```bash cURL -wcn
+curl -G https://api.steel.dev/v1/sessions \
+ -H "steel-api-key: $STEEL_API_KEY" \
+ --data-urlencode "signal=captcha_encountered" \
+ --data-urlencode "signal=bot_detection_triggered"
+```
+
+- The list leaves out failed sessions unless you pass `status` or `releaseReason`. See [Find Past Sessions](/overview/sessions-api/session-lifecycle#find-past-sessions).
+- The dashboard shows signals in the sessions list and on each session page.
+
+:::callout
+type: help
+### Need help with session signals?
+Reach out to us on the #help channel on [Discord](https://discord.gg/steel-dev) or [@steeldotdev](https://twitter.com/steeldotdev).
+:::