---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/observability/logs
markdown_url: https://steel.dev/docs/observability/logs.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Logs
description: Read a session's browser logs during the run or after it, from the API, the dashboard, the CLI, or the MCP server.
summary: Read a session's browser logs during the run or after it, from the API, the dashboard, the CLI, or the MCP server.
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/agent-traces.md
  - https://steel.dev/docs/observability/signals.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# 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](https://steel.dev/docs/platform/limits#data-retention) lists.

The logs show what the browser did on its own. To see what your agent clicked and typed, use [agent traces](https://steel.dev/docs/observability/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.

**TypeScript**

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

**Python**

```sh
python3 -m venv .venv
source .venv/bin/activate
pip 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.

**TypeScript**

```ts file=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);
}
```

**Python**

```python file=logs.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")
        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:

**TypeScript**

```sh
npx tsx logs.mts
```

**Python**

```sh
python logs.py
```

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.

**TypeScript**

```text nocopy
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
```

**Python**

```text nocopy
2026-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 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:

| 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](https://steel.dev/docs/observability/logs#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`:

```sh
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](https://steel.dev/docs/observability/recordings). 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](https://steel.dev/docs/control/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](https://steel.dev/docs/reference/mcp-tools) lists its inputs.

## Follow logs live

The [Steel CLI](https://steel.dev/docs/control/cli) prints a session's logs and then follows new events as they happen:

```sh
steel sessions logs SESSION_ID --follow
```

Add `--event-type` to show only some types, and `--since` to start at a time. [CLI commands](https://steel.dev/docs/reference/cli) lists every flag.

## Check that it worked

The first line that the program in [Read logs](https://steel.dev/docs/observability/logs#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`.

## Next steps

- [Debug a failed session](https://steel.dev/docs/observability/debug-a-failed-session): Narrow a failure down to one session and one moment before you read its logs.
- [Signals](https://steel.dev/docs/observability/signals): Find the sessions to read logs for, such as the ones that hit a bot block.
