Using Session Recordings

Incorporate browser session replay and leverage session events.

The Sessions API exposes multiple endpoints to retrieve session data, including downloads, logs, and recordings. This guide shows how a recording can be used to integrate session replay into your app. You can also use it to process specific events from the session.

Retrieve recordings using the Browserbase SDK

A session recording is a series of rrweb events that may include user interactions such as mouse clicks or typing into a text box, DOM mutations, or CSS transitions. These events are ordered chronologically and comprise the core data structure that rrweb uses for session recording and replay.

Recordings can be retrieved via the Sessions API or by using the SDK as shown here:

1

Install the SDK

2

Import and initialize the SDK

Before using the SDK, be sure to set your BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID environment variables. To get your API key and project ID, refer to the Settings page in your Dashboard as described in the Start your first Session Quickstart.

Node.js

import Browserbase from "browserbase";

// Provide the sessionId for the session recording of interest
const sessionId = 'fef4db93-9995-4147-be1c-27ebb0228ea6';
const BROWSERBASE_API_KEY = process.env.BROWSERBASE_API_KEY!;

(async function main() {
  const bb = new Browserbase(BROWSERBASE_API_KEY)

  const session = await bb.sessions.retrieve(sessionId)

  console.log(session.status) // -> 'COMPLETED'
})();

3

Retrieve the session recording data

Node.js

import Browserbase from "browserbase";

const sessionId = 'fef4db93-9995-4147-be1c-27ebb0228ea6';

(async function main() {
  const bb = new Browserbase(BROWSERBASE_API_KEY)

  const data = await bb.sessions.recording.retrieve(sessionId)
})();

Session recordings are retained through the data retention period before being scheduled for automatic deletion. The duration is based on the plan you’ve chosen: * Hobby Plan: 7 days * Startup Plan: 30 days * Scale Plan: 90+ days, with the option to set a custom retention window.

Integrate a recording player in your app

rrweb provides a player used to replay session recordings, as shown here:

The rrweb player as it appears in action, replaying a browser session performing a Google search.

1

Install the rrweb-player package

rrweb also provides an rrweb React package allowing you to control the player from React components.

2

Instantiate the recording player

The rrweb player directly consumes session recording events. Here’s how to implement the player:

import rrwebPlayer from "rrweb-player";
import Browserbase from "browserbase";
import "rrweb-player/dist/style.css";
const BROWSERBASE_API_KEY = process.env.BROWSERBASE_API_KEY!;

const bb = new Browserbase(BROWSERBASE_API_KEY);

// Provide the sessionId for the session recording of interest
const events = await bb.sessions.recording.retrieve(sessionId);

new rrwebPlayer({
  target: document.body, // customizable root element
  props: {
    events,
  },
});

The complete list of available options for rrwebPlayer() can be found here.

Working with session events

You can use session records to filter and process specific events. Each session recording event has the following format:

JSON

{
  "id": "4b9e95fb-86d8-45ad-9143-c04f35eb9334",
  "type": 0,
  "timestamp": 1716989439884,
  "data": {},
  "sessionId": "fef4db93-9995-4147-be1c-27ebb0228ea6"
}

The type property is an integer matching the following categories of events:

Type Value	Event Name
0	DomContentLoaded
1	Load
2	FullSnapshot
3	IncrementalSnapshot
4	Meta
5	Custom
6	Plugin

The IncrementalSnapshot event describe an incremental page update. The specific kind of IncrementalSnapshot update can be found in its data.source property (e.g. data.source: 5 indicates an input event).

Retrieving recording events

This example script retrieves a recording to collect user interactions during a hybrid web automation session—one that combines programmatic actions with live user actions—for subsequent processing:

Node.js

import Browserbase from "browserbase";
import { EventType, IncrementalSource } from "@rrweb/types";

(async function main() {
  const BROWSERBASE_API_KEY = process.env.BROWSERBASE_API_KEY!;
  const bb = new Browserbase(BROWSERBASE_API_KEY);

  // Provide the sessionId for the session recording of interest
  const recordings = await bb.sessions.recording.retrieve(sessionId);
  const userActions = recordings.filter(
    (event) =>
      event.type &&
      event.type === EventType.IncrementalSnapshot &&
      event.data &&
      // we want to keep track of any mouse or input events performed on the page
      [
        IncrementalSource.Input,
        IncrementalSource.MouseInteraction,
        IncrementalSource.MouseMove,
      ].includes(event.data.source),
  );

  // ... store `userActions` for later use
})();

The complete list of IncrementalSnapshot event types can be found here.