TL;DR Today you can curl a Browserbase session and get back HLS. List the tabs in a session, fetch a .m3u8 for any of them, hand it to hls.js (or Shaka, or video.js, or Safari natively), and you're done. The same fMP4 segments that power our session replay, embedded directly in your product.

What is Session Replay?

Every browser session you run on Browserbase records itself by default. Frames, tab switches, the lot, captured as the session happens and stored for 31 days. We've been using this in our own dashboard for a while. Open any session in our dashboard and you get a scrubbable video timeline, a tab switcher, and synchronized network and console panels alongside the playback. When a browser agent does something strange at 3 AM, that's where you go to see the exact frames it saw.

Many of our customers have been using that view and asking for the same recording, but inside their product instead of ours. A QA tool that drops the failing run next to the bug report, a support dashboard where the end-user replays the agent that booked their flight, an internal review surface where ops looks over sessions without bouncing into Browserbase.

What’s new with Session Replays?

Our new Session Replay API allows you to stream completed browser session replays when you want, wherever you want.

The new surface fits into the API you already use. There are two endpoints, both gated by your existing x-bb-api-key, and live on your backend so the key never reaches a browser. The first lists every tab a session recorded; the second hands back the HLS playlist for whichever one you ask for.

// 1. List the tabs (pages) recorded in a session
const pages = await fetch(
	`https://api.browserbase.com/v1/sessions/${SESSION_ID}/replays`,
	{ headers: { "x-bb-api-key": BROWSERBASE_API_KEY } },
).then((r) => r.json());

// 2. Fetch the HLS playlist for any page
const playlist = await fetch(
	`https://api.browserbase.com/v1/sessions/${SESSION_ID}/replays/0`,
	{ headers: { "x-bb-api-key": BROWSERBASE_API_KEY } },
).then((r) => r.text());

The metadata response is a list of pages, ordered by pageId ascending, with millisecond offsets from the moment the session started (not Unix epoch):

{
	"pages": [
		{ "pageId": "0", "url": "/v1/sessions/0a4c.../replays/0", "startTimeMs": 0,     "endTimeMs": 121382 },
		{ "pageId": "1", "url": "/v1/sessions/0a4c.../replays/1", "startTimeMs": 13001, "endTimeMs": 121382 }
	],
	"pageCount": 2
}

Each url is a relative path against our API (https://api.browserbase.com), and a session can record up to ten concurrent tabs. Hand the second endpoint to any HLS-compatible player and you'll get back a standard VOD .m3u8 whose segment URLs are pre-signed CloudFront links, which means the browser pulls bytes straight from our CDN with your servers nowhere in the loop. No re-encoding, no custom token format, no SDK.

Embed it in your dashboard

Pick whichever player your stack already has. The playlist URL is the same in all four.

For example:

<!-- hls.js: the default for Chromium and Firefox -->
<video id="replay" controls muted autoplay playsinline></video>
<script src="<https://cdn.jsdelivr.net/npm/hls.js@1>"></script>
<script>
	const hls = new Hls();
	hls.loadSource("/your-backend-route/replay.m3u8");
	hls.attachMedia(document.getElementById("replay"));
</script>

Shaka Player, video.js, and Safari's native <video src=".m3u8"> all work too; the docs have the boilerplate for each.

The integration pattern we recommend

Three hops, no proxying segments:

  1. Your backend hits GET /v1/sessions/:id/replays/:pageId with x-bb-api-key, gets back a .m3u8, forwards the body to your frontend unchanged.
  2. Your frontend points its HLS player at your backend route. The player parses the manifest and starts requesting segments.
  3. The browser fetches segments directly from CloudFront using the pre-signed URLs embedded in the playlist.
// example backend impl. The only place the API key lives.
app.get("/replay/:sessionId/:pageId", async (c) => {
	const { sessionId, pageId } = c.req.param();
	const res = await fetch(`{{<https://api.browserbase.com/v1/sessions/${sessionId}>}}/replays/${pageId}`,
		{ headers: { "x-bb-api-key": process.env.BROWSERBASE_API_KEY! } },
	);
	return new Response(await res.text(), {
		headers: { "content-type": "application/vnd.apple.mpegurl" },
	});
});

Two things this gives you for free. The API key never reaches a browser (and never gets leaked in the client). And segments stream directly from the CDN to your end-user, so you don't pay double-egress to proxy them through your servers.

Whats next?

For most of the last year, session replay was something you could look at inside our dashboard. That was the right starting point, most of the work was getting the recording itself trustworthy, getting encoding off the critical path, getting multiple tab recording right.

Now, the same fMP4 segments that power Session Inspector are now reachable from your backend with a key you already have, behind a .m3u8 any player understands. You can stream session replays in your own product. Drop a failing agent run next to the bug report in your QA tool. Show an end-user the exact session that booked their flight. Let ops review overnight runs without ever opening our dashboard. The recording was always yours, now the surface is too.

Get started with our new Session Replay Streaming with the docs here.