/investigate

Investigating with sessions

Load this file when the investigation concerns user journeys, frontend behavior, or session replays.

When to reach for sessions

• The user reports a frontend bug — "checkout broken", "infinite spinner", "empty state"
• You need to reconstruct what a user saw and did
• You have a session ID and want to pull events, logs, and errors within that session
• You're correlating frontend events with backend traces using a shared user identifier or timestamp

Tool guidance (query-sessions)

The query-sessions tool returns sessions with user details and core attributes.

• start_date is required.
• query filters by attributes — e.g. identifier='user@example.com' AND has_errors=true.
• count defaults to 10, max 50.
• sort_field — created_at, length. Defaults to created_at.
• sort_desc — Boolean. Defaults to true.

Fetching a specific session by secure_id. Use a wide time window (you often don't know when the session happened):

{"start_date": "2026-01-01T00:00:00Z", "query": "secure_id=LWK4jxZch4GMmVYJ0rW3R6CNymSy", "count": 1}

Session IDs in output. When you reference sessions in your response, wrap session IDs in <session-id> tags so the UI can turn them into links:

<session-id>c6wX2TtznM6F0QByEiRBoQBFw1Bv</session-id>

Supporting tools

• query-timeline-events — pull the event timeline from a session (navigations, clicks, errors, network). Use this to find the exact moment a user hit a problem.
• query-logs — pass secure_session_id=<id> in the query to get logs scoped to the session. start_date = session created_at, end_date = created_at + 3 hours.

Typical patterns

1. Bug reproduction — start with the symptom ("infinite spinner on checkout"), find sessions that hit the target URL via query="visited-url=*/checkout*", use query-timeline-events to walk chronologically and find the last successful action vs. the first failing one.
2. User-specific investigation — query="identifier=<email>" or by user ID. Pull recent sessions, look for errors or abnormal patterns.
3. Correlated backend errors — sessions with has_errors=true connect to error groups via the trace_id attribute in session events. Cross-reference.

Interpreting results

• Walk chronologically. The transition from the last successful action to the first failing one is where the interesting detail sits.
• Cite exact timestamps. "Around 2:00 into the replay" is less useful than an absolute time.
• If the session is truncated or missing segments, say so explicitly.
• Pull errors as a separate query rather than paraphrasing from the session payload — the error group record has the stack trace.

Common mistakes

• Forgetting to wrap session IDs in <session-id> tags. The UI can't link them otherwise.
• Filtering by user identifier without a time window. Returns all sessions ever — expensive and noisy.
• Using query-timeline-events for overview when you only need a high-level triage read, or skipping it when you actually need chronological detail. Match the tool to the depth you need.