Use the Session recordings API

The Sessions API exposes multiple endpoints to retrieve downloads, logs, and recordings. This guide showcases how recordings can be used to integrate a session replay into your application or retrieve specific events performed during a session.

​

Retrieve recordings using the SDK

A Session’s recording is a collection of rrweb events like DOM changes and user actions.

Recordings can be retrieved via the Sessions API or by using the SDK as showcased below:

npm install -S @browserbasehq/sdk

import { Browserbase } from "@browserbasehq/sdk";

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

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

Let’s now see how to use a Session’s recordings to set up a replay player and how to work with it to filter specific events.

​

Integrate a Session player in your application

rrweb provides a complete Player to replay Browser Session recordings:

The rrweb player in action, replaying a Browser Session performing a Google Search.

The Session’s Recording data can be directly provided to the rrweb Player:

npm install -S rrweb-player

import rrwebPlayer from 'rrweb-player';
import { Browserbase } from "@browserbasehq/sdk";

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


const browserbase = new Browserbase()

// assuming the `sessionId` is parsed from the URL
const events = await browserbase.getSessionRecording(sessionId)

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

​

Working with Session recordings

The Session recordings are rrweb events of the following shape:

{
  "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 events describe incremental page updates, including user interactions (mouse, input), dom mutations, or style updates. The kind of IncrementalSnapshot update can be found in the data.source property (ex: data.source: 5 matches an input event).

​

Example

The following code snippet retrieves recordings to collect the actions performed by a user during hybrid automation (automation that mixes programmatic actions and live user actions) to later automate them:

import { Browserbase, SessionRecording } from "@browserbasehq/sdk";
import { EventType, IncrementalSource } from "@rrweb/types";

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

  // assuming that `sessionId` is fetched from the database
  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 automation
})();