---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/observability/agent-traces
markdown_url: https://steel.dev/docs/observability/agent-traces.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Agent traces
description: See what an agent did in a session as a timeline of clicks, inputs, and navigations, in step with the recording.
summary: See what an agent did in a session as a timeline of clicks, inputs, and navigations, in step with the recording.
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/signals.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Agent traces

An agent trace is the timeline of the actions in a session: each click, input, scroll, drag, page load and error, with the page and element where it happened. Use it to find the step where an agent went wrong without watching the whole recording, to review what an agent did, or to turn a run into a script.

Steel builds the trace from what happened in the browser, not from what the agent says that it did. It holds the actions of every client connected to the session: your agent, your own scripts and a person in the live view.

## Open the timeline

1. Open the session viewer, the session's page in the Steel dashboard. Its URL is in `sessionViewerUrl`.
2. Select the **Agent Traces** tab, next to **Logs**. If the panel is hidden, click **Show traces and logs** in the bar at the top of the page.

Each row is one action. It says what happened in a few words, such as `Navigated to example.com`, with the time since the session started. Steel groups small events into the actions that a person would describe. For example, a burst of typing is one input.

The timeline and the [recording](https://steel.dev/docs/observability/recordings) move together. Select a row to move the video to that moment. Expand a row to see its details: the element's role, name, text and selectors, the pointer or keys, and a picture from the recording near that moment.

## Fetch traces from the API

Call `sessions.agentTraces` (`sessions.agent_traces` in Python, `Sessions.AgentTraces` in Go and `sessions().agent_traces` in Rust) to get the same timeline as JSON. It works while the session runs and after it ends. The method needs `steel-sdk` 0.21.0 or later, and the program below also needs Playwright:

**TypeScript**

```sh
npm install steel-sdk playwright
```

**Python**

```sh
python3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwright
```

This program opens a page in a session, then prints the time and type of each action in the trace. Steel stores an event a moment after it happens, so the program reads the trace every 2 seconds until the load of `example.com` is there. It stops with an error after 30 seconds.

**TypeScript**

```ts file=traces.mts
import Steel from "steel-sdk";
import { chromium } from "playwright";

type TraceEvent = { timestamp: string; type: string; navigation?: { url: string } };

const client = new Steel();
const session = await client.sessions.create();

async function readTrace(sessionId: string) {
  const trace = await client.sessions.agentTraces(sessionId);
  return trace.events as TraceEvent[];
}

try {
  const browser = await chromium.connectOverCDP(session.websocketUrl);
  const context = browser.contexts()[0];
  const page = context.pages()[0] ?? (await context.newPage());
  await page.goto("https://example.com");
  await browser.close();

  const deadline = Date.now() + 30_000;
  let events = await readTrace(session.id);
  while (!events.some((event) => event.navigation?.url.startsWith("https://example.com"))) {
    if (Date.now() > deadline) throw new Error("The trace has no load of example.com after 30 seconds.");
    await new Promise((resolve) => setTimeout(resolve, 2000));
    events = await readTrace(session.id);
  }
  for (const event of events) {
    console.log(event.timestamp, event.type);
  }
} finally {
  await client.sessions.release(session.id);
}
```

**Python**

```python file=traces.py
import time

from playwright.sync_api import sync_playwright
from steel import Steel

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

try:
    with sync_playwright() as playwright:
        browser = playwright.chromium.connect_over_cdp(session.websocket_url)
        context = browser.contexts[0]
        page = context.pages[0] if context.pages else context.new_page()
        page.goto("https://example.com")
        browser.close()

    deadline = time.monotonic() + 30
    trace = client.sessions.agent_traces(session.id)
    while not any(
        event.get("navigation", {}).get("url", "").startswith("https://example.com")
        for event in trace.events
    ):
        if time.monotonic() > deadline:
            raise RuntimeError("The trace has no load of example.com after 30 seconds.")
        time.sleep(2)
        trace = client.sessions.agent_traces(session.id)
    for event in trace.events:
        print(event["timestamp"], event["type"])
finally:
    client.sessions.release(session.id)
```

Run the program with your API key in `STEEL_API_KEY`:

**TypeScript**

```sh
npx tsx traces.mts
```

**Python**

```sh
python traces.py
```

The trace has two events: the blank page that the session starts with, and the load of `example.com`.

```text nocopy
2026-11-16T03:58:46.904Z navigate
2026-11-16T03:58:48.656Z navigate
```

The response has `events` (oldest first), `total` and `hasMore`. A click event looks like this:

```json nocopy
{
  "type": "click",
  "timestamp": "2026-11-10T09:14:21.345Z",
  "page": { "url": "https://steel.dev/practice/login" },
  "target": {
    "role": "button",
    "accessibleName": "Login",
    "selector": { "css": "form#login > button" }
  },
  "pointer": { "x": 520, "y": 410 }
}
```

Every event has `type` and `timestamp`, and most events have `page`. An action that lasts some time has `endTimestamp`. When Steel can name the element, the event has `target`. Other fields depend on the type: `pointer` for a click, `value` for an input, `keyboard` for a key, `navigation` for a page load, and `error` for an error. Check that an event has `target` before you use it, because navigations and errors often have none.

Without `limit`, the call returns the whole trace. To read it in pages, pass `limit`, up to 1000, and `offset`. Both count actions, not raw events. Steel builds the trace from the session's first 10,000 raw events. To read part of a session, pass `startTime` and `endTime` as UTC times in ISO 8601. When Steel captured no browser actions in a session, as in older sessions, it builds a simpler trace from the session's CDP commands. If there are none, the list is empty.

Over HTTP, send `GET /v1/sessions/{id}/agent-traces`:

```sh
curl https://api.steel.dev/v1/sessions/$SESSION_ID/agent-traces \
  -H "steel-api-key: $STEEL_API_KEY"
```

`GET /v1/sessions/{id}/agent-logs` returns the raw CDP events behind the trace, such as `Input.dispatchMouseEvent`. The SDKs have no method for it. Use the trace unless you need those events.

### With the CLI

The [Steel CLI](https://steel.dev/docs/control/cli) prints the trace, and follows new actions while the session runs:

```sh
steel sessions traces SESSION_ID --follow
```

### Over the MCP server

The [MCP server](https://steel.dev/docs/control/mcp-server) has a `session_traces` tool. It returns a session's newest clicks, key presses, form fills and page loads, one line each, with a CSS selector for each element, so that an agent can write a script that repeats them. It shows the length of typed text, never the text. [MCP tools](https://steel.dev/docs/reference/mcp-tools) lists its inputs.

## Export a trace

The **Agent Traces** tab has two exports, as buttons beside the tab names. On a phone, they are in the **More actions** menu.

| Export | What you get | Use it when |
| - | - | - |
| **Copy traces** | One Markdown document on your clipboard, with a heading for each page and a numbered step for each action. | Another agent or a teammate must read the run, or reproduce it. |
| **Download traces** | A ZIP file with the same Markdown document, as `prompt.md`, and a picture of each page from the recording. While the recording is not ready, you get the Markdown file alone. | You attach the run to a bug report, a support ticket or an audit. |

For the actions as JSON, use [the API](https://steel.dev/docs/observability/agent-traces#fetch-traces-from-the-api).

The Markdown export reads like a recipe. Paste it into Claude Code, Codex or Cursor with a request such as `write me a Steel script that reproduces this run`. A shortened example:

```md nocopy
# Browser session

Recording of a real user's interaction with a web app, structured for replay by an automation agent. Read top to bottom.

## https://steel.dev/practice/login

1. `0:02.345` **Click** textbox "Username"
   - name: `username`
   - CSS: `input#username`
2. `0:04.802` **Type** <redacted, 20 chars> into textbox "Password"
   - name: `password`
   - CSS: `input#password`

*(idle 12s)*

3. `0:17.430` **Click** button "Login"
   - type: `submit`
   - CSS: `form#login > button`
```

> **Warning**
>
> The exports replace the values of password fields and credit card fields. Other values that the agent typed can appear in them. Read an export before you share it.

## Check that it worked

Print the session's `sessionViewerUrl` (`session_viewer_url` in Python) in the program in [Fetch traces from the API](https://steel.dev/docs/observability/agent-traces#fetch-traces-from-the-api), and open it after the run. In the **Agent Traces** tab, the timeline has the load of `example.com` that the program printed as its last `navigate` event. Select that row, and the recording moves to the moment that `example.com` loads.

## Next steps

- [Logs](https://steel.dev/docs/observability/logs): Read the requests, responses and page errors around an action.
- [Debug a failed session](https://steel.dev/docs/observability/debug-a-failed-session): Compare the element that the agent acted on with the one that it should have acted on.
