Session replay

Session replay records what a user saw and did in your web app. You can watch the session that led to an error, then open the logs, traces, and issues of the same session.

Record sessions

Session replay is part of @squasher-ai/browser, and it is on by default. After you set up the browser SDK, the SDK records every session. To record only some sessions, or to turn replay off, set replay in init:

src/main.ts

import { init } from "@squasher-ai/browser";

init({
  apiKey: import.meta.env.VITE_SQUASHER_API_KEY,
  projectId: import.meta.env.VITE_SQUASHER_PROJECT_ID,
  replay: {
    enabled: true,
    sampleRate: 0.1,
    privacy: { blockSelector: "[data-private]" },
  },
});

Option	Default	Effect
`enabled`	`true`	`false` turns replay off. Required when you pass `replay`.
`sampleRate`	`1`	The share of page loads to record, from `0` to `1`.
`privacy.maskAllText`	`true`	Masks all page text and the `aria-label`, `placeholder`, `title`, and `value` attributes.
`privacy.maskAllInputs`	`true`	Masks all typed values. Password fields are always masked.
`privacy.blockAllMedia`	`true`	Shows images, video, audio, SVG, canvas, and embeds as empty boxes.
`privacy.maskSelector`	None	When `maskAllText` is `false`, masks the text of elements that match this CSS selector.
`privacy.blockSelector`	None	Shows the elements that match this CSS selector as empty boxes.
`privacy.ignoreSelector`	None	Does not record typing in the inputs that match this CSS selector.

Replay is private by default, like the defaults of other replay tools. Some protections always apply, whatever the options are:

Password inputs are masked.
Payment card (autocomplete="cc-*"), one-time-code, and password-manager fields are left out.
File inputs are not recorded.
The page URL is recorded without its query string or fragment, so reset tokens and sign-in codes are not kept.

To mark elements in your HTML, add the squasher-mask or squasher-block class, or the data-squasher-mask or data-squasher-block attribute. squasher-ignore stops typing capture for an input.

Set maskAllText: false only on pages without personal data. Masking happens in the browser before upload and cannot be undone.

Replay records the URL, method, status, duration, and size of network requests. It does not record request or response bodies or headers.

Find a session

Open your project and select Replays in the sidebar. The Replays list opens.
Search by URL, user, or session ID, or pick a signal under Signals:
- Errors: the session logged at least one error.
- Failed requests: a request failed or returned a status of 400 or more.
- Engaged: 5 or more clicks, or 3 or more pages.
- Bounced: one page, and under 10 seconds or no clicks.
- Long: longer than 95% of the loaded sessions.
- Mostly idle: over a minute long and active less than 15% of the time.

Each row shows the entry page and the pages the user went to next, the errors, failed requests, and clicks, the active time inside the session length, the Duration, and when the session Started. Runs of three or more short visits with no problems fold into one row; select the row to show them. On an issue page, Watch replay opens the session of the latest event with that error, 3 seconds before the error.

Watch a session

Select a session to open its page. The player is on the left and the session details are on the right.

The timeline under the player shows user activity above the track, idle time as hatched stripes, page changes as ticks, and a mark for each problem: a diamond for an error, a square for a failed request, and a triangle for a rage click, a dead click, or a slow request. Long idle stretches take less room, so the active part of a long session stays readable.
Skip idle jumps over stretches of 10 seconds or more without input. Speed is 1×, 2×, 4×, or 8×. Next problem plays from the next problem. Press Space to play or pause, and the arrow keys to move 5 seconds.
Summary says what happened, lists the findings with the times to watch, and has Hand off to an agent: the prompt, the transcript, and a Playwright test that walks the same pages and clicks. The summary is built from the recording and the session’s logs; no model is used.
Steps lists every page view, click, input, failed request, error, and idle stretch in order. The step at the playhead is marked, and Follow keeps it in view. Select a step to play from it.
Network lists the recorded requests with their status and duration.
Logs lists the logs that carry the session ID, from the browser and from your backend services, with a link to each trace.
Info has the session facts and links to the session’s errors, logs, and issues.

Typed values are never shown: a step says which field was typed in, not what was typed. The page URL is the session’s own link; add ?t=90 to start at 1:30. Session stories replace values of URL query parameters with secret-related names, such as token, password, and code, with redacted. This applies to absolute and relative request URLs in the story, findings, and exported transcript. URL credentials and data fragments are removed; section fragments such as #plans are kept. This filter does not change the stored recording.

How sessions count

A session is one browser tab visit. Each new session counts once toward the monthly replay allowance of your organization, however many segments it has. On Free, new sessions are refused when the allowance is used. Replays use the replay retention period of the organization that owns the project. See Plans and limits. Replay uploads for one session can arrive at the same time. Each accepted batch gets a unique segment index. If the browser retries the same batch, Squasher returns the saved index and does not count that batch or its storage usage again. Active time is bounded by the session duration. Replay error counts include linked browser and backend error logs that carry a session ID.

Use replays from the CLI

squasher replays search --project "$SQUASHER_PROJECT_ID" --from 2026-09-01T00:00:00Z --to 2026-09-02T00:00:00Z
squasher replays story --project "$SQUASHER_PROJECT_ID" <session_id>
squasher replays inspect --project "$SQUASHER_PROJECT_ID" <session_id>

squasher replays story prints the session as text: a summary, the findings, and one line for each page view, click, failed request, and error, with the time from the start of the session. Errors that your backend services log with the same session ID are included. Add --json for the full response. Coding agents can read the same story through the MCP server (replays.story). See Replays API.

Get started

Guides

Record sessions

Find a session

Watch a session

How sessions count

Use replays from the CLI

Next steps

Browser SDK

Privacy and data handling

​Record sessions

​Find a session

​Watch a session

​How sessions count

​Use replays from the CLI

​Next steps

Browser SDK

Privacy and data handling

Record sessions

Find a session

Watch a session

How sessions count

Use replays from the CLI

Next steps