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.
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.
npm install steel-sdk playwrightpython3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwrightIn Go and Rust, install only the SDK, as the Go and Rust 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 and 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.
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);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:
npx tsx record.mtspython record.pyhttps://app.steel.dev/sessions/b5661faf-8be2-489b-a200-3a2f6716d78bOpen 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 https://api.steel.dev/v1/sessions/$SESSION_ID/hls \
-H "steel-api-key: $STEEL_API_KEY"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();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.textimport (
"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
}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:
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");
}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()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)
}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, 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.
<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.
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 says how long Steel keeps them. The live view still works while the session runs.
const session = await client.sessions.create({ recording: false });session = client.sessions.create(recording=False)session, err := client.Sessions.New(ctx, steel.SessionNewParams{
Recording: steel.F(false),
})
if err != nil {
return err
}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 prints, and fetch its playlist as Fetch the recording shows. The playlist is text that starts with #EXTM3U. Play it in the page from 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 lists it. Save what you need from a recording before the period ends.
Troubleshooting
This session has no recording
{
"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: Check why the session ended before you watch the whole recording.