Recordings

Hyperbrowser allows you to record and replay your browser sessions. It uses , an open-source web session replay library. Session recordings let you:

• Visually debug test failures and errors

• Analyze user behavior and interactions

• Share reproducible bug reports

• Save and archive session data

Enabling Session Recording

To record a session, set the enableWebRecording option to true when creating a new Hyperbrowser session:

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const main = async () => {
  const session = await client.sessions.create({
    enableWebRecording: true,
  });
};

main();

import asyncio
import os
from dotenv import load_dotenv
from hyperbrowser import AsyncHyperbrowser
from hyperbrowser.models.session import CreateSessionParams

load_dotenv()

client = AsyncHyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


async def main():
    session = await client.sessions.create(
        params=CreateSessionParams(
            enable_web_recording=True,
        )
    )


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())

This will record all browser interactions, DOM changes, and network requests for the duration of the session.

Retrieving Recordings

1. Note the id of the session you want to replay

2. Use the Session Recordings API to download the recording, or if you are using the SDKs, you can just call the getRecordingURL function:

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const main = async () => {
  const recordingData = await client.sessions.getRecordingURL(
    "91e96d43-0dd2-4882-8d3a-613b12583ba2"
  );
};

main();

import asyncio
import os
from dotenv import load_dotenv
from hyperbrowser import AsyncHyperbrowser

load_dotenv()

client = AsyncHyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


async def main():
    recording_data = await client.sessions.get_recording_url(
        "91e96d43-0dd2-4882-8d3a-613b12583ba2"
    )


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())

curl -X GET 'https://app.hyperbrowser.ai/api/session/{sessionId}/recording-url' \
-H 'x-api-key: YOUR_API_KEY

The response will have the following data (will be Snake case if using python SDK):

status: "not_enabled" | "pending" | "in_progress" | "completed" | "failed"
recordingUrl: string | null
error: string | null | undefined

Replaying Recordings

Using rrweb's Player

Here's an example of using rrweb's player to replay a recording:

1. Include the rrweb player script on your page:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/rrweb@latest/dist/rrweb.min.css"/>
<script src="https://cdn.jsdelivr.net/npm/rrweb@latest/dist/rrweb.min.js"></script>

1. Add a container element for your player

<div id="player"></div>

1. Initialize the player with your recording data

// if using rrweb npm package
import rrwebPlayer from "rrweb-player";
import "rrweb-player/dist/style.css";

const recordingData = YOUR_RECORDING_DATA

const replayer = new rrwebPlayer({
  target: document.getElementById('player'),
  props: {
    events: recordingData,
    showController: true,
    autoPlay: true,
  },
});

This will launch an interactive player UI that allows you to play, pause, rewind, and inspect the recorded session.

Building a custom player

Storage and Retention

Session recordings are stored securely in Hyperbrowser's cloud infrastructure. Recordings are retained according to your plan's data retention policy.

Limitations

• Session recordings capture only the visual state of the page. They do not include server-side logs, database changes, or other non-DOM modifications.

• Recordings may not perfectly reproduce complex WebGL or canvas-based animations.