> ## Documentation Index > Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt > Use this file to discover all available pages before exploring further. # Replays API > List replay sessions, inspect replay metadata, and fetch stored replay segment payloads. Use the Replays API to inspect recorded browser sessions and fetch the segment payloads used by the dashboard replay player. ## List replay sessions ```text theme={null} GET https://api.squasher.ai/v1/projects/{project_id}/replays ``` 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 ```text theme={null} GET https://api.squasher.ai/v1/projects/{project_id}/replays/search?from={iso_time}&to={iso_time} ``` 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 ```text theme={null} GET https://api.squasher.ai/v1/projects/{project_id}/replays/{session_id} ``` Returns the same replay summary rollups as the list endpoint plus the indexed segment list for that session. ## Inspect replay timeline ```text theme={null} GET https://api.squasher.ai/v1/projects/{project_id}/replays/{session_id}/inspect ``` 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. ```bash theme={null} squasher replays search --project \ --from 2026-05-01T00:00:00Z \ --to 2026-05-02T00:00:00Z \ --fields session_id,first_url,error_count squasher replays inspect --project \ --include page,replay_error,network \ --limit 50 ``` Both commands also accept structured JSON filters: ```bash theme={null} squasher replays search --project \ --input '{"from":"2026-05-01T00:00:00Z","to":"2026-05-02T00:00:00Z","fields":["session_id","first_url"]}' squasher replays inspect --project \ --input '{"include":["page","network"],"slow_network_ms":1500}' ``` Print the runtime input/output shape with: ```bash theme={null} squasher replays schema search squasher replays schema inspect ``` ## Get one replay segment payload ```text theme={null} GET https://api.squasher.ai/v1/projects/{project_id}/replays/{session_id}/events?segment={segment_index} ``` 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: ```text theme={null} Find relevant Squasher replay sessions for project from to . Search with field masks and error/network filters, inspect one candidate timeline, and ask before fetching raw replay events. ``` Use `squasher replays search`, `squasher replays inspect`, or MCP `search("replays.search")` and `search("replays.inspect")`.