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.
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, or 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. |
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. |
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. |
context_restored | Context restored | success | The session started from a profile. 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 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.