Skip to main content
Use the Replays API to inspect recorded browser sessions and fetch the segment payloads used by the dashboard replay player.

​
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.

​
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. 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 and inspect through Code Mode. Use the search tool to discover replays.search or replays.inspect, then call the operation through execute. 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 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 and inspect surfaces for agent and headless workflows. 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 inspect, or MCP search("replays.search") and search("replays.inspect").