Skip to main content
A replay is a recording of one browser session. Use this API to find sessions, read what happened in them, and fetch the same segment payloads that the dashboard replay player uses.

​
List replay sessions

Returns replay summaries including session timing, retention expiration, deletion state, segment-read availability, first/all page URLs, compact interaction counts, active milliseconds, console/network counts, AI tags/highlight state, replay source/library metadata, SDK package/version metadata, replay storage footprint, and derived replay-linked error counts. SDK package/version fields are nullable; final uploads sent through navigator.sendBeacon may not include SDK metadata because browsers do not allow custom headers on beacon requests.

​
Search replay sessions

Searches persisted replay rollups without loading raw replay events. The response is compact by default and includes the selected fields, clamped limit, applied order, and a replays array. Query parameters:
  • from / to - required ISO 8601 timestamps; ranges must be bounded to 31 days or less
  • limit - optional result limit; defaults to 25 and clamps to 100
  • order - optional sort order: started_at_desc, started_at_asc, created_at_desc, created_at_asc, active_ms_desc, interaction_count_desc, console_error_count_desc, or network_failed_count_desc
  • url, environment, release, source, library - optional exact or URL substring filters
  • ai_tag, ai_freeform_tag, ai_highlighted - optional AI enrichment filters
  • min_interactions, min_console_logs, min_console_warnings, min_console_errors, min_network_failed - optional non-negative threshold filters
  • fields - optional comma-separated replay summary field mask, such as session_id,first_url,error_count,ai_tags,ai_highlighted
Validation errors use stable machine-readable codes: replay_search_invalid_time_range, replay_search_invalid_filter, replay_search_invalid_order, replay_search_limit_too_large, and replay_search_invalid_field_mask. Replay summaries include retention_expires_at, retention_state, segment_reads_allowed, deleted_at, deleted_reason, ai_tags, ai_freeform_tags, ai_highlighted, ai_enrichment_status, ai_enriched_at, and ai_enrichment_error. List and search omit deleted sessions; direct detail/inspect responses can still explain a retained tombstone when one exists. Legacy retained sessions that cannot be tied to a known plan use retention_state: "unknown" and keep segment reads allowed.

​
Get one replay session

Returns the same replay summary rollups as the list endpoint plus the indexed segment list for that session.

​
Read the story of a session

Start here to understand one session. The story lists what the user did and what went wrong, in order: one step for each page view, click, input, failed or slow request, browser error, and backend error. It is built from the recording and from the log lines tagged with the session ID, so errors that your backend services log with the same session ID show up next to the clicks that caused them. The dashboard replay page shows the same story. Query parameters:
  • format - optional; json (default) or text. text returns a text/plain transcript.
The JSON response has four fields:
  • replay - the replay summary, the same shape as the list and get endpoints.
  • story - the story:
    • summary - one or two sentences about the session.
    • findings - the problems and friction found, such as errors, backend errors, failed requests, rage clicks, dead clicks, and slow requests. Each finding has a title, a detail, a count, and up to 20 offsets_ms. Error findings include the fingerprint and trace_ids.
    • steps - one entry per page, click, input, failed or slow request, error, backend error, and idle period. Each step has a kind, a tone (problem, friction, or neutral), an offset_ms, a label, and a count for repeated steps.
    • pages, requests, and logs - the page views, network requests, and session log lines that the steps point to.
    • idle, activity, duration_ms, active_ms, viewport, and truncated.
  • coverage - segments_loaded, segments_missing, and partial. partial is true when some recorded segments could not be read.
  • segments - the segment list the replay player needs: segment_index, event_count, started_at, ended_at, and size_bytes.
Offsets are milliseconds from the first recorded event, the same clock that the replay player uses. Steps name the field that the user typed in, never the typed value. The story reads up to 300 session log lines (errors first) from one minute before the session starts to five minutes after it ends. When the recording can no longer be read (for example, after the replay retention period), the story is built from the stored page visits and the session logs. coverage.segments_loaded is 0, and the story has no idle periods. With format=text, the response is a transcript:
Validation errors use stable machine-readable codes: replay_story_invalid_filter, replay_story_invalid_format, and replay_story_invalid_session_id. A missing or expired session returns 404.

​
Inspect replay timeline

Returns the replay summary, segment list, and a bounded timeline of important replay moments. Timeline moment types include page visits, replay-linked errors, console events, failed or slow network requests, active/inactive windows, and segment boundaries. replay_error moments also include, when known, the first line of the error message (up to 500 characters), the error group fingerprint, the trace_id, the service that logged the error, and the log event_id. Query parameters:
  • include - optional comma-separated categories: page, replay_error, console, network, activity, segment
  • exclude - optional comma-separated categories to remove after include is applied
  • limit - optional timeline limit; defaults to 100 and clamps to 200
  • slow_network_ms - optional slow-network threshold in milliseconds; defaults to 1000
Validation errors use stable machine-readable codes: replay_inspect_invalid_category, replay_inspect_invalid_filter, replay_inspect_invalid_session_id, and replay_inspect_limit_too_large.

​
MCP replay workflows

The hosted MCP server exposes replay search, story, and inspect through Code Mode. Use the search tool to discover replays.search, replays.story, or replays.inspect, then call the operation through execute. To understand one session, call replays.story first; use replays.inspect when you need timeline categories or segment boundaries. Code Mode returns the query schema, response schema, generated TypeScript, and example squasher.request(...) call for each operation. Replay segment payloads remain API/CLI-only because they can contain large raw rrweb event payloads. Agents should use replays.search, replays.story, and replays.inspect first, then ask a user before fetching raw segment events outside MCP.

​
CLI replay workflows

The Squasher CLI exposes the same search, story, and inspect surfaces for agent and headless workflows. replays story prints the text transcript by default; add the global --json flag for the JSON response (and --pretty to indent it). Search and inspect print compact JSON by default; add --pretty when reading output interactively.
Both commands also accept structured JSON filters:
Print the runtime input/output shape with:

​
Get one replay segment payload

Query parameters:
  • segment - required zero-based replay segment index
The response contains the stored rrweb event payload for that segment. Deleted or expired replays return 410 with stable JSON error codes: replay_deleted or replay_expired. Missing replay metadata returns replay_not_found, and missing indexed segment metadata returns replay_segment_not_found.

​
Agent handoff

Agents should use replay search and inspect before raw event payloads:
Use squasher replays search, squasher replays story, squasher replays inspect, or MCP search("replays.search"), search("replays.story"), and search("replays.inspect").