---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/observability/recordings
markdown_url: https://steel.dev/docs/observability/recordings.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Recordings
description: Replay a session after it ends. Steel records each session, and you can fetch the recording to show it in your own app.
summary: Replay a session after it ends.
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/logs.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
---

# Recordings

Steel records each headful session as a video, so you can watch what the browser showed after the session ends. Use the recording to find the step where a task went wrong, or to show a run to a customer. Recording is on by default.

A headless session records page events instead of a video. See [Fetch the recording](https://steel.dev/docs/observability/recordings#fetch-the-recording).

## 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 programs use a browser that Steel runs.

**TypeScript**

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

**Python**

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

In Go and Rust, install only the SDK, as the [Go](https://steel.dev/docs/reference/sdks/go#install) and [Rust](https://steel.dev/docs/reference/sdks/rust#install) SDK pages show. The code that drives the browser uses Playwright, so it is in TypeScript and Python only.

## Replay in the dashboard

A session's `sessionViewerUrl` opens the session viewer, its page in the Steel dashboard. After the session ends, the viewer plays the recording next to the session's [logs](https://steel.dev/docs/observability/logs) and [agent traces](https://steel.dev/docs/observability/agent-traces). Select an action in the agent traces to move the recording to that moment.

This program opens a page in a session, releases the session, and prints the URL where you can watch the recording.

**TypeScript**

```ts file=record.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.waitForTimeout(3000);
  await browser.close();
} finally {
  await client.sessions.release(session.id);
}

console.log(session.sessionViewerUrl);
```

**Python**

```python file=record.py
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.wait_for_timeout(3000)
        browser.close()
finally:
    client.sessions.release(session.id)

print(session.session_viewer_url)
```

Run the program:

**TypeScript**

```sh
npx tsx record.mts
```

**Python**

```sh
python record.py
```

```text nocopy
https://app.steel.dev/sessions/b5661faf-8be2-489b-a200-3a2f6716d78b
```

Open the URL. The recording shows the browser opening `example.com`.

## Fetch the recording

A headful session's recording is an HLS playlist, an `.m3u8` file that lists the parts of the video. Get it from `GET /v1/sessions/{id}/hls` with your API key. The playlist is ready a few seconds after the session ends. Until then, the endpoint returns `404`, so these examples ask again every 2 seconds, for up to 30 seconds. A headless session and a session with recording off have no playlist, and the endpoint returns the same `404` for them. Fetch the playlist only for a headful session with recording on. The playlist is text, not JSON and not an MP4 file. Play it with any player that supports HLS.

**cURL**

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

**TypeScript**

```ts
let response: Response | undefined;
for (let attempt = 0; attempt < 15; attempt++) {
  response = await fetch(`https://api.steel.dev/v1/sessions/${session.id}/hls`, {
    headers: { "steel-api-key": process.env.STEEL_API_KEY! },
  });
  if (response.status !== 404) break;
  await new Promise((resolve) => setTimeout(resolve, 2_000));
}
if (!response?.ok) throw new Error(`No recording: ${response?.status}`);
const playlist = await response.text();
```

**Python**

```python
import os
import time

import httpx

for attempt in range(15):
    response = httpx.get(
        f"https://api.steel.dev/v1/sessions/{session.id}/hls",
        headers={"steel-api-key": os.environ["STEEL_API_KEY"]},
    )
    if response.status_code != 404:
        break
    time.sleep(2)
response.raise_for_status()
playlist = response.text
```

**Go**

```go
import (
	"errors"
	"io"
	"net/http"
	"time"
)

var playlist string
for attempt := 1; ; attempt++ {
	response, err := client.Sessions.Hls(ctx, session.ID)
	var apierr *steel.Error
	if errors.As(err, &apierr) && apierr.StatusCode == http.StatusNotFound && attempt < 15 {
		time.Sleep(2 * time.Second)
		continue
	}
	if err != nil {
		return err
	}
	body, err := io.ReadAll(response.Body)
	response.Body.Close()
	if err != nil {
		return err
	}
	playlist = string(body)
	break
}
```

**Rust**

```rust
let mut attempt = 1;
let response = loop {
    match client.sessions().hls(&session.id).await {
        Err(error) if error.status() == Some(404) && attempt < 15 => {
            attempt += 1;
            tokio::time::sleep(std::time::Duration::from_secs(2)).await;
        }
        result => break result?,
    }
};
let playlist = String::from_utf8(response.to_vec())?;
```

The playlist links to the video parts with signed URLs. They need no API key, and they stop working after 6 hours. Fetch the playlist again when you need it, and do not store it.

A headless session records page events in the rrweb format instead of a video. Get them with `sessions.events`, and play them with `rrweb-player`. The endpoint returns the events in pages. When more events are left, the response has a `Next-Cursor` header. Pass its value as `pointer` to get the next page. The SDK method returns only the body, so this code reads the header from the raw response:

**TypeScript**

```ts
let result = await client.sessions.events(session.id).withResponse();
const events = result.data;
let cursor = result.response.headers.get("Next-Cursor");
while (cursor) {
  result = await client.sessions.events(session.id, { pointer: cursor }).withResponse();
  events.push(...result.data);
  cursor = result.response.headers.get("Next-Cursor");
}
```

**Python**

```python
response = client.sessions.with_raw_response.events(session.id)
events = response.parse()
while cursor := response.headers.get("Next-Cursor"):
    response = client.sessions.with_raw_response.events(session.id, pointer=cursor)
    events += response.parse()
```

**Go**

```go
import (
	"net/http"

	"github.com/steel-dev/sdk/go/option"
)

var events []interface{}
params := steel.SessionEventsParams{}
for {
	var response *http.Response
	result, err := client.Sessions.Events(ctx, session.ID, params, option.WithResponseInto(&response))
	if err != nil {
		return err
	}
	events = append(events, *result...)
	cursor := response.Header.Get("Next-Cursor")
	if cursor == "" {
		break
	}
	params.Pointer = steel.F(cursor)
}
```

**Rust**

```rust
let events = client
    .sessions()
    .events(&session.id, steel_rs::SessionEventsParams::default())
    .await?;
```

The Rust SDK does not return response headers, so in Rust this call gets only the first page. To read the rest, send `GET /v1/sessions/{id}/events` over HTTP and read the header yourself.

## Embed a replay

To show a recording in your app, serve the playlist from your own server, and play it with an HLS player in the page. The API key stays on your server. The page loads the playlist from your server, and the video parts straight from their signed URLs.

On the server, add a route that checks that the user may see the session, fetches the playlist as in [Fetch the recording](https://steel.dev/docs/observability/recordings#fetch-the-recording), and returns it with the type `application/vnd.apple.mpegurl`.

In the page, play it with the hls.js library. Safari plays HLS without it.

```html
<video id="player" controls playsinline style="width: 100%"></video>
<script type="module">
  import Hls from "https://cdn.jsdelivr.net/npm/hls.js@^1.5.0/dist/hls.mjs";

  const playlistUrl = "/recordings/SESSION_ID.m3u8";
  const video = document.getElementById("player");

  if (Hls.isSupported()) {
    const hls = new Hls();
    hls.loadSource(playlistUrl);
    hls.attachMedia(video);
  } else if (video.canPlayType("application/vnd.apple.mpegurl")) {
    video.src = playlistUrl;
  }
</script>
```

Replace `/recordings/SESSION_ID.m3u8` with your server's route.

> **Warning**
>
> Do not put your API key in the page or in a frontend bundle. Anyone who loads the page can read it, and the key can create sessions on your account.

## Turn recording off

Set `recording` to `false` when you create the session. Steel then stores no video of the session. It still stores the session's logs and agent traces, which can hold URLs and typed text. [Data retention](https://steel.dev/docs/platform/limits#data-retention) says how long Steel keeps them. The [live view](https://steel.dev/docs/observability/live-view) still works while the session runs.

**TypeScript**

```ts
const session = await client.sessions.create({ recording: false });
```

**Python**

```python
session = client.sessions.create(recording=False)
```

**Go**

```go
session, err := client.Sessions.New(ctx, steel.SessionNewParams{
	Recording: steel.F(false),
})
if err != nil {
	return err
}
```

**Rust**

```rust
let session = client
    .sessions()
    .create(steel_rs::SessionCreateParams {
        recording: Some(false),
        ..Default::default()
    })
    .await?;
```

## Check that it worked

Take the session ID from the end of the URL that the program in [Replay in the dashboard](https://steel.dev/docs/observability/recordings#replay-in-the-dashboard) prints, and fetch its playlist as [Fetch the recording](https://steel.dev/docs/observability/recordings#fetch-the-recording) shows. The playlist is text that starts with `#EXTM3U`. Play it in the page from [Embed a replay](https://steel.dev/docs/observability/recordings#embed-a-replay): the video shows the browser opening `example.com`, as the session viewer does. For a session with `recording` set to `false`, the same request returns `404`.

## Retention

Each plan has a data retention period. [Limits](https://steel.dev/docs/platform/limits#data-retention) lists it. Save what you need from a recording before the period ends.

## Troubleshooting

### This session has no recording

```json nocopy
{
  "error": "Not Found",
  "message": "This session has no recording.",
  "retryable": false
}
```

**Cause:** Steel has no video for the session. The session ran with `recording: false`, or it was headless.

**Fix:** For a headless session, fetch its events with `sessions.events`. For a new session, leave `recording` out or set it to `true`, and keep `headless` off.

**Verify:** Fetch the playlist again. The response starts with `#EXTM3U`.

### The video stops playing after a few hours

**Cause:** The page loaded the playlist more than 6 hours ago. The video parts' signed URLs have expired.

**Fix:** Load the playlist again from your server before you play the video. Do not cache it for more than 6 hours.

**Verify:** Play the video from the start to the end.

## Next steps

- [Debug a failed session](https://steel.dev/docs/observability/debug-a-failed-session): Check why the session ended before you watch the whole recording.
