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 "@browserbasehq/sdk";

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

(async function main() {
  const browserbase = new Browserbase()

  const session = await browserbase.getSession(sessionId)

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

Retrieve the session recording data

Node.js
import { Browserbase } from "@browserbasehq/sdk";

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

(async function main() {
  const browserbase = new Browserbase()

  const data = await browserbase.getSessionRecording(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 "@browserbasehq/sdk";

import "rrweb-player/dist/style.css";

const browserbase = new Browserbase();

// Provide the sessionId for the session recording of interest
const events = await browserbase.getSessionRecording(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 ValueEvent Name
0DomContentLoaded
1Load
2FullSnapshot
3IncrementalSnapshot
4Meta
5Custom
6Plugin

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, SessionRecording } from "@browserbasehq/sdk";
import { EventType, IncrementalSource } from "@rrweb/types";

(async function main() {
  const browserbase = new Browserbase();

  // Provide the sessionId for the session recording of interest
  const recordings = await browserbase.getSessionRecording(sessionId);
  const userActions: SessionRecording[] = [];

  for (let event of recordings) {
    if (
      event.type &&
      event.type === EventType.IncrementalSnapshot &&
      event.data
    ) {
      // we want to keep track of any mouse or input events performed on the page
      if (
        [
          IncrementalSource.Input,
          IncrementalSource.MouseInteraction,
          IncrementalSource.MouseMove,
        ].includes(event.data.source)
      ) {
        userActions.push(event);
      }
    }
  }

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

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