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
- Open the session viewer, the session's page in the Steel dashboard. Its URL is in
sessionViewerUrl. - 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 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:
npm install steel-sdk playwrightpython3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwrightThis 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.
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);
}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:
npx tsx traces.mtspython traces.pyThe trace has two events: the blank page that the session starts with, and the load of example.com.
2026-11-16T03:58:46.904Z navigate
2026-11-16T03:58:48.656Z navigateThe response has events (oldest first), total and hasMore. A click event looks like this:
{
"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:
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 prints the trace, and follows new actions while the session runs:
steel sessions traces SESSION_ID --followOver the MCP server
The 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 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., 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.
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:
# 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`Check that it worked
Print the session's sessionViewerUrl (session_viewer_url in Python) in the program in 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.