Using Session Recordings

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:

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'
})();

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)
})();

​

Integrate a recording player in your app

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

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,
  },
});

​

Working with session events

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

{
  "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:

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:

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
})();