Logs
A session's logs are its browser's events: console messages, page errors, network requests and responses, failed requests, and page loads. Read them to find out why a page did not work, for example a script error or a request that failed. You can read them while the session runs and after it ends. Steel keeps them for your plan's data retention period, which Limits lists.
The logs show what the browser did on its own. To see what your agent clicked and typed, use agent traces.
Before you begin
Put your Steel API key in the STEEL_API_KEY environment variable. Then install the Steel SDK and Playwright. You do not need to run playwright install, because the program uses a browser that Steel runs. sessions.logs needs steel-sdk 0.21.0 or later.
npm install steel-sdk playwrightpython3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwrightRead logs
Call sessions.logs with the session ID. While the session is live, it returns the newest events first. After the session ends, it returns the oldest events first.
This program opens a page, writes a message to the page's console, and prints each log event's time and type. Steel stores an event a moment after it happens, so the program reads the logs every 2 seconds until the console message is there. It stops with an error after 30 seconds.
import Steel from "steel-sdk";
import { chromium } from "playwright";
const client = new Steel();
const session = await client.sessions.create();
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 page.evaluate(() => console.log("Hello from the page"));
await browser.close();
const deadline = Date.now() + 30_000;
let logs = await client.sessions.logs(session.id);
while (!logs.events.some((event) => event.type === "Console")) {
if (Date.now() > deadline) throw new Error("The console message is not in the logs after 30 seconds.");
await new Promise((resolve) => setTimeout(resolve, 2000));
logs = await client.sessions.logs(session.id);
}
for (const event of logs.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")
page.evaluate("console.log('Hello from the page')")
browser.close()
deadline = time.monotonic() + 30
logs = client.sessions.logs(session.id)
while not any(event.type == "Console" for event in logs.events):
if time.monotonic() > deadline:
raise RuntimeError("The console message is not in the logs after 30 seconds.")
time.sleep(2)
logs = client.sessions.logs(session.id)
for event in logs.events:
print(event.timestamp, event.type)
finally:
client.sessions.release(session.id)Run the program:
npx tsx logs.mtspython logs.pyThe program reads the logs before it releases the session, so it prints the newest event first: the console message, then the responses, requests and page loads before it.
2026-11-16T03:58:37.876Z Console
2026-11-16T03:58:37.210Z Response
2026-11-16T03:58:37.185Z Request
2026-11-16T03:58:37.172Z Navigation
2026-11-16T03:58:37.167Z Response
2026-11-16T03:58:37.116Z Request
2026-11-16T03:58:35.550Z Navigation2026-11-16 03:58:43.260000+00:00 Console
2026-11-16 03:58:42.681000+00:00 Response
2026-11-16 03:58:42.657000+00:00 Request
2026-11-16 03:58:42.641000+00:00 Navigation
2026-11-16 03:58:42.637000+00:00 Response
2026-11-16 03:58:42.579000+00:00 Request
2026-11-16 03:58:40.602000+00:00 NavigationThe response has events, total and hasMore. Each event has an id, a timestamp, a type and a log, which holds the event's details as a JSON string. Parse log to read them.
sessions.logs takes these parameters:
| Parameter | What it does |
|---|---|
startTime, endTime | Only events at or after, and at or before, these UTC times in ISO 8601, such as 2026-11-10T09:14:00Z. |
eventTypes | Only events of these types. See What the logs hold. |
limit | How many events to return. The default is 100 and the maximum is 1000. |
offset | How many events to skip. When hasMore is true, add the number of events that you read to get the next page. |
namespace | The namespace to read. The default is the session's namespace. |
Over HTTP, send GET /v1/sessions/{id}/logs:
curl "https://api.steel.dev/v1/sessions/$SESSION_ID/logs?limit=100" \
-H "steel-api-key: $STEEL_API_KEY"In the dashboard
Open the session viewer at the session's sessionViewerUrl, and select the Logs tab beside the recording. It shows the same events in one list: console messages, errors, page loads, and network requests and responses. Expand a row to see its details. The buttons beside the tab copy the logs as JSON, or download them as a JSON file with the session's details.
Over the MCP server
The MCP server has a session_logs tool, so that an agent can read a session's logs while the session runs or after it ends. It returns the newest events, in time order, as one line each. By default it returns console messages, errors and page loads. Add network to its types to get each request and response with its status code. MCP tools lists its inputs.
Follow logs live
The Steel CLI prints a session's logs and then follows new events as they happen:
steel sessions logs SESSION_ID --followAdd --event-type to show only some types, and --since to start at a time. CLI commands lists every flag.
Check that it worked
The first line that the program in Read logs prints is the Console event. Parse its log with JSON.parse (json.loads in Python): it holds the text Hello from the page that the program wrote to the console. The Logs tab of the session viewer lists the same message.
What the logs hold
Each event has one of these types:
| Type | What it records |
|---|---|
Console | A message that the page wrote to its console, with its level. |
PageError | An error that a page script did not catch. |
Error | An error in the session. |
BrowserError | An error in the browser. |
Request | A request that the page sent, with its method, URL and resource type. |
Response | A response that the page received, with its status code, URL and content type. |
RequestFailed | A request that did not get a response, with its URL and the error. |
Navigation | A page load, with its URL. |
To start with the errors, pass PageError, Error, BrowserError and RequestFailed in eventTypes.