Session Replay

This guide covers how to enable Session Replay for your BQL sessions, view the recordings, and understand its limitations. It also explains how Session Replay differs from BaaS Screen Recording.

Prerequisites

• A paid Browserless plan (Prototyping, Starter, Scale, or Enterprise) — Session Replay is not available on the free plan
• A Browserless API token from your account dashboard

What is Session Replay

Session Replay captures BQL sessions as interactive replays viewable in your Browserless dashboard. Using RRWeb technology, it records DOM mutations, mouse movements, clicks, scrolling, keyboard input, console logs, and network requests. The recordings are lightweight and can be played back at any speed.

This is different from Screen Recording (record=true), which captures WebM video files and is only available for BaaS connections, not BQL.

Use Session Replay for debugging BQL automation workflows, creating visual documentation, and troubleshooting mutations with recorded evidence.

What Gets Recorded

Session Replay captures DOM events (all visual changes to the page), user interactions (mouse movements, clicks, scrolling, keyboard input), console logs (all console output with timestamps), and network requests (HTTP requests and responses).

Sensitive input values are masked. See What's masked for the rules.

Recording a Session with BQL

Connection String Configuration

To enable session recording with BQL, add the replay=true parameter to your connection URL. Recording starts automatically when you connect.

https://production-sfo.browserless.io/chromium/bql?token=YOUR_API_TOKEN_HERE&replay=true

Recording Starts Automatically

When you connect with replay=true, recording begins immediately. There is no need to call a start mutation. The recording continues until the BQL query completes or you explicitly stop it.

Basic Recording Example

CURL

curl --request POST \
  --url 'https://production-sfo.browserless.io/chrome/bql?token=YOUR_API_TOKEN_HERE&replay=true' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "mutation replay {\n  goto(url: \"https://www.browserless.io\") {\n    time\n  }\n  click(selector: \"a\") {\n    time\n  }\n  waitForTimeout(time: 2000) {\n    time\n  }\n}",
    "variables": {},
    "operationName": "replay"
  }'

JavaScript

import fetch from 'node-fetch';

const API_KEY = "YOUR_API_TOKEN_HERE";
const BQL_ENDPOINT = `https://production-sfo.browserless.io/chromium/bql?replay=true&token=${API_KEY}`;

const recordingQuery = `
mutation replay {
  goto(url: "https://www.browserless.io") {
    time
  }
  click(selector:"a"){
    time
  }
  waitForTimeout(time:2000){
    time
  }
}`;

const recordSession = async () => {
  const response = await fetch(BQL_ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ query: recordingQuery,
"operationName":"replay" })
  });

  const result = await response.json();
  console.log('Recording Result:', JSON.stringify(result, null, 2));

  // Session recording automatically stops when the BQL query completes
  console.log('Session recorded successfully');
};

recordSession().catch(console.error);

Python

import requests
import json

API_KEY = "YOUR_API_TOKEN_HERE"
BQL_ENDPOINT = f"https://production-sfo.browserless.io/chromium/bql?replay=true&token={API_KEY}"

recording_query = """
mutation RecordSession {
  goto(url: "https://www.example.com") {
    status
    time
  }

  click(selector: "button.example") {
    time
    x
    y
  }

  type(selector: "input[name='search']", text: "browserless") {
    time
  }

  waitForSelector(selector: ".search-results") {
    time
  }
}
"""

def record_session():
    response = requests.post(
        BQL_ENDPOINT,
        headers={
            'Content-Type': 'application/json'
        },
        json={'query': recording_query}
    )

    result = response.json()
    print('Recording Result:', json.dumps(result, indent=2))

    # Session recording automatically stops when the BQL query completes
    print('Session recorded successfully')

if __name__ == "__main__":
    record_session()

Stop Recording Manually

For long-running sessions or when you need precise control over when recording stops, use the stopSessionRecording mutation. This mutation stops the recording and uploads the captured data to your dashboard.

CURL

curl --request POST \
  --url 'https://production-sfo.browserless.io/chrome/bql?token=YOUR_API_TOKEN_HERE&replay=true' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "mutation StopRecording {\n  goto(url: \"https://www.browserless.io\") {\n    status\n    time\n  }\n  waitForTimeout(time: 5000) {\n    time\n  }\n  stopSessionRecording {\n    success\n    error\n  }\n}",
    "variables": {},
    "operationName": "StopRecording"
  }'

JavaScript

import fetch from 'node-fetch';

const API_KEY = "YOUR_API_TOKEN_HERE";
const BQL_ENDPOINT = `https://production-sfo.browserless.io/chromium/bql?replay=true&token=${API_KEY}`;

const recordingQuery = `
mutation StopRecording {
  goto(url: "https://www.browserless.io") {
    status
    time
  }
  waitForTimeout(time: 5000) {
    time
  }
  stopSessionRecording {
    success
    error
  }
}`;

const recordSession = async () => {
  const response = await fetch(BQL_ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: recordingQuery,
      operationName: "StopRecording"
    })
  });

  const result = await response.json();
  console.log('Recording Result:', JSON.stringify(result, null, 2));

  if (result.data?.stopSessionRecording?.success) {
    console.log('Session recording stopped and uploaded successfully');
  }
};

recordSession().catch(console.error);

The stopSessionRecording mutation returns a response with success (boolean indicating if the recording was stopped successfully) and error (error message if the operation failed, null otherwise).

Viewing Replays

After your BQL query completes (or after calling stopSessionRecording), the replay is automatically uploaded and available in your Browserless dashboard. Navigate to the Session Replay section to find your recorded sessions. Each replay includes a timeline showing all captured events, console logs, and network activity.

Retention and privacy

How long replays are kept

How long a replay is kept depends on your plan when Browserless registers it:

Plan	Replays kept for
Prototyping	7 days
Starter	30 days
Scale	90 days
Dedicated, Enterprise and other plans	30 days

Each replay has its own retention period, so recording a new session doesn't extend older ones, and changing plans doesn't change how long existing replays are kept.

• An hourly cleanup deletes expired replays, removing both the dashboard entry and the stored recording.
• Failed deletions are retried, so a replay can outlast its retention period. Recordings stored before this retention policy took effect can take longer to clear from storage.
• You can delete one replay or all of them from the dashboard. If storage is temporarily unavailable, the deletion fails instead of hiding a recording that may still exist.

What's masked

Replays mask sensitive input values, but masking is pattern-based, not a guarantee.

A field's value is always masked when:

• It's a password, email, or phone field.
• Its markup identifies it as a card number, security code, expiry date, email address, or password. Browserless checks the field's type, autocomplete value, name, ID, placeholder, data-testid, and aria-label. Visible label text isn't checked.

In any other text field, the value is masked once it looks like a card number (seven or more digits, or a run of 13 or more) or contains @. The first few digits of a card number typed into an unlabeled field can appear before masking starts.

All text inputs are fully masked while an interactive LiveURL viewer is connected, and after Browserless fills a stored credential.

These aren't masked:

• Other text fields, such as names and search boxes, so you can debug form flows.
• A short password or security code typed into a field with no recognizable type, autocomplete value, or name.
• Checkboxes, radio buttons, and buttons.
• Text the page displays, such as a card number echoed on a confirmation screen. Masking only covers input values.

Sharing replays

Only the account that recorded a replay can request a link to it. The dashboard and the Browserless MCP server open replays through a signed link that expires after 15 minutes, and request a new link each time.

warning

Until it expires, a signed replay link works for anyone who has it, without signing in. Treat it like a password and don't share it.

To share a replay, download it from the dashboard. Treat downloaded files as sensitive too: even with masking, a replay can contain page content, interactions, console output, and network activity. Only share them with people you trust.

Navigation Handling

Session Replay automatically handles page navigations within your BQL session. When mutations like goto navigate to a new page, the recording system reinjects the RRWeb recorder and continues capturing events. All data from multiple page navigations is aggregated into a single replay.

Limitations

• Cross-origin iframes may not be fully captured due to browser security restrictions.
• Very long sessions with high DOM activity may produce large replay files.
• WebGL or canvas content may not be perfectly reproduced in playback.

FAQ & Troubleshooting

My session replay is empty or not appearing in the dashboard

Ensure your BQL query completed successfully. If the browser session was terminated before the recording could upload, the replay won't appear. Check that your API token is on a paid plan (Prototyping, Starter, Scale, or Enterprise) — Session Replay isn't available on the free plan.

Can I use Session Replay with BaaS connections?

Yes. Add replay=true to your BaaS connection URL. See BaaS Session Replay for examples. Session Replay isn't the same as Screen Recording, which captures WebM video files.

Next steps

BQL best practices

guidance on writing reliable BQL scripts

BQL IDE

debug queries with the browser-based editor

Screen recording (BaaS)

WebM video capture for BaaS sessions