---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/observability/signals
markdown_url: https://steel.dev/docs/observability/signals.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Signals
description: Signals mark what happened in a session, such as a CAPTCHA, a bot block, or a proxy failure. Read them after the session ends.
summary: Signals mark what happened in a session, such as a CAPTCHA, a bot block, or a proxy failure.
type: how-to
reviewed: 2026-11-12
prerequisites: []
related:
  - https://steel.dev/docs/observability/embed-a-live-browser.md
  - https://steel.dev/docs/observability/hand-control-to-a-human.md
  - https://steel.dev/docs/observability/recordings.md
  - https://steel.dev/docs/observability/logs.md
  - https://steel.dev/docs/observability/agent-traces.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Signals

Signals are labels that Steel adds to a session after the session ends. They mark events from the run, such as a CAPTCHA, a bot block or a proxy failure. Use them to find the sessions to check, without opening each recording. You do not set signals. To add your own labels, use [metadata](https://steel.dev/docs/sessions/metadata).

## Before you begin

Put your Steel API key in the `STEEL_API_KEY` environment variable, and install the Steel SDK for your language: [TypeScript](https://steel.dev/docs/reference/sdks/typescript#install), [Python](https://steel.dev/docs/reference/sdks/python#install), [Go](https://steel.dev/docs/reference/sdks/go#install) or [Rust](https://steel.dev/docs/reference/sdks/rust#install).

> **Note**
>
> Signals need `steel-sdk` 0.21.0 or later, in TypeScript and in Python.

## Read a session's signals

A session's `signals` field is an array of signal names. It stays empty while the session runs, and Steel fills it in after the session ends.

This program creates a session with an [`inactivityTimeout`](https://steel.dev/docs/sessions/timeouts#release-idle-sessions) of 5 seconds, so Steel releases it after 5 seconds without activity. The program does nothing in the session. It waits 20 seconds, then prints the session's signals as JSON.

**TypeScript**

```ts file=signals.mts
import Steel from "steel-sdk";

const client = new Steel();
const session = await client.sessions.create({ inactivityTimeout: 5000 });

try {
  console.log(`Created session ${session.id}`);
  await new Promise((resolve) => setTimeout(resolve, 20_000));
  const { signals } = await client.sessions.retrieve(session.id);
  console.log(JSON.stringify(signals));
} finally {
  await client.sessions.release(session.id);
}
```

**Python**

```python file=signals.py
import json
import time

from steel import Steel

client = Steel()
session = client.sessions.create(inactivity_timeout=5000)

try:
    print(f"Created session {session.id}")
    time.sleep(20)
    signals = client.sessions.retrieve(session.id).signals
    print(json.dumps(signals))
finally:
    client.sessions.release(session.id)
```

**Go**

```go file=main.go
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"time"

	"github.com/steel-dev/sdk/go"
)

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) error {
	client := steel.NewClient()
	session, err := client.Sessions.New(ctx, steel.SessionNewParams{
		InactivityTimeout: steel.F(int64(5000)),
	})
	if err != nil {
		return err
	}
	defer func() {
		if _, err := client.Sessions.Release(ctx, session.ID); err != nil {
			log.Print(err)
		}
	}()

	fmt.Printf("Created session %s\n", session.ID)
	time.Sleep(20 * time.Second)
	current, err := client.Sessions.Get(ctx, session.ID)
	if err != nil {
		return err
	}
	signals, err := json.Marshal(current.Signals)
	if err != nil {
		return err
	}
	fmt.Println(string(signals))
	return nil
}
```

**Rust**

```rust file=src/main.rs
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = steel_rs::Client::new();
    let session = client
        .sessions()
        .create(steel_rs::SessionCreateParams {
            inactivity_timeout: Some(5000),
            ..Default::default()
        })
        .await?;

    let result: Result<(), Box<dyn std::error::Error>> = async {
        println!("Created session {}", session.id);
        tokio::time::sleep(std::time::Duration::from_secs(20)).await;
        let current = client.sessions().retrieve(&session.id).await?;
        println!("{}", serde_json::to_string(&current.signals)?);
        Ok(())
    }
    .await;

    client.sessions().release(&session.id).await?;
    result
}
```

In Rust, the program also needs `cargo add serde_json`. Run the program:

**TypeScript**

```sh
npx tsx signals.mts
```

**Python**

```sh
python signals.py
```

**Go**

```sh
go run .
```

**Rust**

```sh
cargo run
```

The session ended on its `inactivityTimeout`, so it has the signal `session_timeout_exceeded`:

```text nocopy
Created session d14e97be-2e61-4f5f-880e-189558bd4bc3
["session_timeout_exceeded"]
```

A session that hit a CAPTCHA and a bot block has this list:

```json nocopy
["captcha_encountered", "bot_detection_triggered"]
```

[Signals reference](https://steel.dev/docs/reference/signals) lists every signal and what it means. It also explains why an empty list does not prove that nothing happened. To learn why a session ended, read its `releaseReason`. See [Session lifecycle](https://steel.dev/docs/sessions/lifecycle).

The sessions that `sessions.list` returns carry the same field. The dashboard shows signals in the session list and in the session viewer.

## Show signals in your app

Steel can add new signal names over time, so handle names that you do not know. To show signals in your own app without a fixed list, call `sessions.signalCatalog` (`sessions.signal_catalog` in Python, `Sessions.SignalCatalog` in Go and `sessions().signal_catalog` in Rust). It returns each current signal with a `label`, a `description` and a `severity` of `info`, `warning`, `danger` or `success`.

**TypeScript**

```ts
const catalog = await client.sessions.signalCatalog();
for (const signal of catalog.signals) {
  console.log(signal.value, signal.label, signal.severity);
}
```

**Python**

```python
catalog = client.sessions.signal_catalog()
for signal in catalog.signals:
    print(signal.value, signal.label, signal.severity)
```

**Go**

```go
catalog, err := client.Sessions.SignalCatalog(ctx)
if err != nil {
	return err
}
for _, signal := range catalog.Signals {
	fmt.Println(signal.Value, signal.Label, signal.Severity)
}
```

**Rust**

```rust
let catalog = client.sessions().signal_catalog().await?;
for signal in catalog.signals {
    println!("{:?} {} {:?}", signal.value, signal.label, signal.severity);
}
```

## Find sessions by signal

Pass `signal` to `sessions.list` to find the sessions that carry a signal. If you pass several signals, a session must carry all of them. Add `metadata` to narrow the search to one job or one customer.

**TypeScript**

```ts
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
for session in client.sessions.list(
    metadata={"job_id": "job-1042"},
    signal=["bot_detection_triggered"],
):
    print(session.id, session.signals)
```

**Go**

```go
iter := client.Sessions.ListAutoPaging(ctx, steel.SessionListParams{
	Metadata: steel.F(map[string]string{"job_id": "job-1042"}),
	Signal:   steel.F([]steel.SessionListParamsSignal{steel.SessionListParamsSignalBotDetectionTriggered}),
})
for iter.Next() {
	session := iter.Current()
	fmt.Println(session.ID, session.Signals)
}
if err := iter.Err(); err != nil {
	return err
}
```

**Rust**

```rust
let sessions = client
    .sessions()
    .list_auto_paging(steel_rs::SessionListParams {
        metadata: Some(std::collections::HashMap::from([(
            "job_id".to_owned(),
            "job-1042".to_owned(),
        )])),
        signal: Some(vec![
            steel_rs::SessionListParamsSignal::BotDetectionTriggered,
        ]),
        ..Default::default()
    });
let mut sessions = std::pin::pin!(sessions);
while let Some(session) = futures_util::StreamExt::next(&mut sessions).await {
    let session = session?;
    println!("{} {:?}", session.id, session.signals);
}
```

In Rust, this code needs `cargo add futures-util`.

Over HTTP, repeat the `signal` parameter for each signal:

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

## Check that it worked

List the sessions that carry `session_timeout_exceeded`, as [Find sessions by signal](https://steel.dev/docs/observability/signals#find-sessions-by-signal) shows. The session that the program in [Read a session's signals](https://steel.dev/docs/observability/signals#read-a-session-s-signals) created is in the list, with the signal that the program printed. The dashboard's session list shows the same signal for it.

## Next steps

- [Get past bot detection](https://steel.dev/docs/stealth/get-past-bot-detection): Decide what to do about the sessions that get blocked.
- [Debug a failed session](https://steel.dev/docs/observability/debug-a-failed-session): Find the step where a flagged session went wrong.
