Finding Sessions To Watch

1---
2name: finding-sessions-to-watch
3description: >
4  Guides a user from "I want to watch recordings but don't know which ones" to a short, high-signal
5  list of sessions worth watching. Use when the user asks which sessions or replays to watch, wants
6  help finding interesting / useful recordings, says they don't know where to start in session replay,
7  or wants to watch sessions about a goal (signup, pricing, onboarding, checkout, a feature, rageclicks,
8  errors, mobile, a specific person) without naming exact filters. Turns a vague intent into a focused
9  RecordingsQuery via `query-session-recordings-list`, then deep-links the best few and hands off to
10  `investigating-replay`. Do NOT use when the user already has a recording/session ID (use
11  investigating-replay) or wants the replay for a known error issue (use finding-replay-for-issue).
12---
13 
14# Finding sessions to watch
15 
16Most people open session replay with a goal ("why are signups dropping?") but no idea which of
17thousands of recordings to watch. A raw, unfiltered list is the worst possible answer — it buries the
18useful sessions in noise. Your job is to turn their intent into a **focused filter**, return a **handful
19of high-signal recordings**, and offer to dig into one.
20 
21The starting points below are the same ones the product surfaces as "filter templates" — they encode
22the jobs people actually use replay for. Treat them as a menu, not a script.
23 
24## The one rule
25 
26**Never dump an unfiltered recording list.** Always either (a) apply a goal-based filter, or (b) sort by
27a signal (activity, errors) so the first few rows are worth a click. If the user's goal is unclear, ask
28one short question or offer the menu before querying.
29 
30## Available tools
31 
32| Tool                                        | Purpose                                                                  |
33| ------------------------------------------- | ------------------------------------------------------------------------ |
34| `posthog:query-session-recordings-list`     | Find/filter recordings (the workhorse). Returns metadata + `id` per row. |
35| `posthog:read-data-schema`                  | Confirm real event names, URLs, and property values before filtering.    |
36| `posthog:execute-sql`                       | Collect `$session_id`s for sessions where a specific **event** happened. |
37| `posthog:cohorts-list`                      | Resolve a cohort name → id when scoping to a user segment.               |
38| `posthog:session-recording-playlist-create` | Save the resulting filter as a saved filter view (`type: 'filters'`).    |
39 
40Hand off to the **`investigating-replay`** skill once the user picks a recording to understand in depth.
41 
42## Workflow
43 
44### 1. Pin down the goal
45 
46Map the request to one of the starting points below. If it's vague ("show me something interesting"),
47offer 3-4 options rather than guessing, or default to **most active sessions** (high signal, no setup).
48 
49### 2. Discover before you filter
50 
51Event names and URLs vary per project — never assume `$pageview` paths, a `signup_completed` event, or
52a person property exists. Confirm with `read-data-schema` (`event_properties`,
53`event_property_values`, `entity_property_values`) before putting a value in a filter. If the needed
54event/property doesn't exist, say so and suggest the closest available signal.
55 
56### 3. Run a minimal query
57 
58Call `query-session-recordings-list` with **only** the filters that serve the goal. Recommended settings:
59 
60- set `filter_test_accounts: true` (the tool defaults to `false`) to exclude internal users, unless the
61  user is debugging their own session.
62- `date_from` of `-7d` to `-30d` for goal-based searches; `-3d` for "recent".
63- A deliberate `order` — `activity_score` for "interesting", `console_error_count` for "broken",
64  `start_time` for "recent".
65- `limit: 10` — you want a shortlist, not a dump.
66 
67### 4. Triage and present
68 
69Don't relay raw rows. Pick the **3-5 most promising** and say why each is worth watching (long active
70duration, many errors, reached the key page, high activity score). Deep-link each as
71`{posthog_base_url}/replay/{id}` — never `/replay/home?sessionRecordingId={id}`. Note total matches so
72the user knows how much is behind the shortlist.
73 
74### 5. Offer the next step
75 
76- "Want me to walk through one?" → `investigating-replay`.
77- "Want to keep watching these?" → save it as a saved filter view with
78  `session-recording-playlist-create` (`type: 'filters'` — a filter view, not a `'collection'`, which is
79  for manually curated recordings and can't carry filters).
80 
81## Starting points → filters
82 
83Two filter shapes cover almost everything:
84 
85- **Reached a page** → recording metric `visited_page` (`{ "type": "recording", "key": "visited_page",
86"operator": "icontains", "value": "/pricing" }`).
87- **Did a specific event** (signup, search, rageclick, used a feature) → there is no event-name filter on
88  the recordings query, so first collect session IDs with `execute-sql`, then pass them as `session_ids`
89  (see the two-step pattern below).
90 
91| User goal                                             | Approach                                                                                                                                                                  |
92| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
93| **Signup / onboarding / pricing / checkout friction** | `visited_page` `icontains` the relevant path (confirm the real path first). Order `start_time`, or `console_error_count` to surface broken ones.                          |
94| **A specific feature**                                | Two-step: `execute-sql` for `$session_id`s where the feature event fired, then `session_ids`. Pair with `visited_page` if the feature lives on one page.                  |
95| **Rageclicks / frustration**                          | Two-step on the `$rageclick` event → `session_ids`.                                                                                                                       |
96| **Errors / something broken**                         | `properties: [{ "type": "recording", "key": "console_error_count", "operator": "gt", "value": 0 }]`, order `console_error_count`.                                         |
97| **A/B test / feature flag**                           | `{ "type": "flag", "key": "<flag-key>", "operator": "flag_evaluates_to", "value": "<variant or true>" }`.                                                                 |
98| **A specific person / segment**                       | `person_uuid`, a `person` property filter (e.g. `email`), or a `cohort` filter (`cohorts-list` for the id).                                                               |
99| **Mobile / responsive issues**                        | `{ "type": "event", "key": "$device_type", "operator": "exact", "value": ["Mobile"] }`, or `{ "type": "event", "key": "$screen_width", "operator": "lt", "value": 600 }`. |
100| **Most active users / "just show me good ones"**      | No filter; `order: "activity_score"`. The reliable default when the user has no specific goal.                                                                            |
101| **Most active pages**                                 | `execute-sql` to rank `$pageview` by URL, then filter recordings by the hottest page's `visited_page`.                                                                    |
102 
103### Two-step pattern: "sessions where event X happened"
104 
105The recordings query filters by event _properties_, not event _names_. To find sessions that contain a
106particular event, collect the session IDs first:
107 
108```sql
109posthog:execute-sql
110SELECT $session_id
111FROM events
112WHERE event = '$rageclick'          -- or your signup/search/feature event (confirm via read-data-schema)
113    AND timestamp > now() - INTERVAL 7 DAY
114    AND $session_id != ''
115GROUP BY $session_id
116ORDER BY max(timestamp) DESC         -- recent first: UUIDs aren't time-ordered, so the LIMIT must keep the freshest sessions
117LIMIT 100
118```
119 
120Then fetch those recordings (some session IDs won't have a recording — that's expected). Pass the same
121`date_from` window as the SQL step — with only `session_ids`, the query falls back to its `-3d` default
122and would drop sessions whose event was older than that:
123 
124```json
125posthog:query-session-recordings-list
126{ "date_from": "-7d", "session_ids": ["<id1>", "<id2>", "..."] }
127```
128 
129## Worked example
130 
131User: "Why are people bouncing on our pricing page? Show me some sessions."
132 
1331. Goal = pricing-page friction → `visited_page` approach.
1342. `read-data-schema` (`event_property_values` for `$pathname`) to confirm the path is `/pricing`.
1353. Query:
136 
137```json
138posthog:query-session-recordings-list
139{
140  "date_from": "-14d",
141  "filter_test_accounts": true,
142  "order": "activity_score",
143  "limit": 10,
144  "properties": [
145    { "type": "recording", "key": "visited_page", "operator": "icontains", "value": "/pricing" }
146  ]
147}
148```
149 
1504. Present the 3-5 most active, each as `{base}/replay/{id}`, noting which lingered or hit errors.
1515. Offer to investigate the most promising one (`investigating-replay`) or save it as a saved filter view (`type: 'filters'`).
152 
153## Tips
154 
155- Prefer one good filter over many — over-filtering returns nothing and reads as "no data".
156- If a query returns zero recordings, widen the date range or loosen the filter before concluding there's
157  nothing to watch; if it's still empty, recordings may not be captured for that flow (point the user to
158  `diagnosing-missing-recordings`).
159- `activity_score` is a solid default proxy for "worth watching" when there's no sharper signal — but it
160  rewards raw interaction volume, so prefer a goal-based filter (errors, a key page) when you have one.
161- Keep the shortlist short. The value is in choosing _for_ the user, not handing back the haystack.
162