Skip to content

Logs

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 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 playwright

Read 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.

logs.mts
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);
}

Run the program:

npx tsx logs.mts

The 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 Navigation

The 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:

ParameterWhat it does
startTime, endTimeOnly events at or after, and at or before, these UTC times in ISO 8601, such as 2026-11-10T09:14:00Z.
eventTypesOnly events of these types. See What the logs hold.
limitHow many events to return. The default is 100 and the maximum is 1000.
offsetHow many events to skip. When hasMore is true, add the number of events that you read to get the next page.
namespaceThe 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 --follow

Add --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:

TypeWhat it records
ConsoleA message that the page wrote to its console, with its level.
PageErrorAn error that a page script did not catch.
ErrorAn error in the session.
BrowserErrorAn error in the browser.
RequestA request that the page sent, with its method, URL and resource type.
ResponseA response that the page received, with its status code, URL and content type.
RequestFailedA request that did not get a response, with its URL and the error.
NavigationA page load, with its URL.

To start with the errors, pass PageError, Error, BrowserError and RequestFailed in eventTypes.

Next steps