---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/reference/signals
markdown_url: https://steel.dev/docs/reference/signals.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Signals reference
description: Look up every signal that Steel can put on a session, with what triggers it and what to do next.
summary: Look up every signal that Steel can put on a session, with what triggers it and what to do next.
type: reference
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/reference/mcp-tools.md
  - https://steel.dev/docs/reference/commands.md
  - https://steel.dev/docs/reference/proxy-locations.md
  - https://steel.dev/docs/reference/errors.md
  - https://steel.dev/docs/reference/glossary.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Signals reference

A signal marks an event that Steel saw during a session, such as a CAPTCHA, a bot block or a proxy failure. To read signals and to find sessions by signal, see [Signals](https://steel.dev/docs/observability/signals).

## Signals

A session's `signals` field is a list of these values. Steel fills it in after the session ends. Until then, the list is empty.

| Signal | Label | Severity | What it means | What to do next |
| - | - | - | - | - |
| `captcha_encountered` | Captcha encountered | `warning` | Steel detected a CAPTCHA during the session. | Turn on [CAPTCHA solving](https://steel.dev/docs/stealth/captcha-solving), or [hand control to a human](https://steel.dev/docs/observability/hand-control-to-a-human). |
| `proxy_connection_failed` | Proxy failed | `danger` | The proxy connection failed or was unreliable. | Create a new session to get a new IP address, or check your own proxy. See [Proxies](https://steel.dev/docs/stealth/proxies). |
| `session_timeout_exceeded` | Timeout exceeded | `info` | The session ended on its `timeout` or its `inactivityTimeout`. | Raise the limit, or release the session when the task ends. See [Set timeouts](https://steel.dev/docs/sessions/timeouts). |
| `bot_detection_triggered` | Bot blocked | `warning` | A page ended on an anti-bot block or challenge that the browser did not get past. | See [Get past bot detection](https://steel.dev/docs/stealth/get-past-bot-detection). |
| `context_restored` | Context restored | `success` | The session started from a [profile](https://steel.dev/docs/logins/profiles). A session that starts with `sessionContext` does not get this signal. | Nothing. The signal confirms that the profile loaded. |

A signal records that Steel saw the event at some time during the session. It does not describe the page's final state. A session with `captcha_encountered` may have solved the CAPTCHA and finished the task. Detection uses heuristics and does not cover every case, so an empty list does not prove that nothing happened.

Steel can add new signals in the future. Write your code to accept a signal that it does not know.

The signal `session_timeout_exceeded` is not the error code of the same name. The [error](https://steel.dev/docs/reference/errors) rejects a request whose `timeout` is longer than the plan allows.

## Signal catalog

`GET /v1/sessions/signals/catalog` returns the current signals, so that your own interface can show them without a list in your code. In the SDKs, the method is `client.sessions.signalCatalog()` in TypeScript and `client.sessions.signal_catalog()` in Python.

Each entry of `signals` has these fields:

| Field | Type | Description |
| - | - | - |
| `value` | string | The signal, as it appears in a session's `signals` field. |
| `label` | string | A short name to show to a person. |
| `description` | string | What the signal means. |
| `source` | string | `manual` or `derived`. Every signal on this page is `derived`. Steel adds it from what it records during the session. |
| `severity` | string | `info`, `warning`, `danger` or `success`. |

The response also has a `semantics` field, a string that states the limits of signals.
