Skip to content

Signals reference

Set up your agent

Give your coding agent a Steel browser and the Steel skills, so that it browses and writes Steel code the right way. Learn more

Install the Steel CLI. It signs you in and installs the skills for your coding agents.

curl -fsS https://setup.steel.dev | sh

Or send this prompt to your coding agent, and it does the same:

Read https://setup.steel.dev/install.md and follow it to set up Steel for this coding client.
Then continue my requested task using the installed Steel skill.

Set up your agent →

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.

SignalLabelSeverityWhat it meansWhat to do next
captcha_encounteredCaptcha encounteredwarningSteel detected a CAPTCHA during the session.Turn on CAPTCHA solving, or hand control to a human.
proxy_connection_failedProxy faileddangerThe 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_exceededTimeout exceededinfoThe session ended on its timeout or its inactivityTimeout.Raise the limit, or release the session when the task ends. See Set timeouts.
bot_detection_triggeredBot blockedwarningA page ended on an anti-bot block or challenge that the browser did not get past.See Get past bot detection.
context_restoredContext restoredsuccessThe 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:

FieldTypeDescription
valuestringThe signal, as it appears in a session's signals field.
labelstringA short name to show to a person.
descriptionstringWhat the signal means.
sourcestringmanual or derived. Every signal on this page is derived. Steel adds it from what it records during the session.
severitystringinfo, warning, danger or success.

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