aaronbali Fullstory Audience Lens
The goal is to turn a vague behavioural question ("who are these users?") into a concrete, characterised cohort with session evidence — so a business user understands not just that a problem exists, but who it's affecting and what their experience looks like. Think of it as putting a face on a metric.
Step 1 — Understand the question
Before querying anything, be clear on what cohort you're building:
- What behaviour defines this cohort? (e.g. rage clicking on Add to Cart, abandoning at billing, seeing an error modal)
- What time window? Default to last 30 days unless the user specifies.
- Is this tied to a specific page, funnel step, or org event? Check the org context file (below) for the right IDs.
If the question is vague ("who are the frustrated users?"), use get_opportunities to surface the biggest known issues and ask the user to pick one to focus on — don't try to characterise all frustrated users at once.
Step 2 — Load org context
Load ~/claude/accounts/{slug}-fullstory-context.md if available. You need it to map the user's question to the right event IDs, page IDs, and element IDs.
If no context file exists, run get_managed_funnels and discover_org_context with relevant queries to orient yourself before building the segment.
Step 3 — Build the segment
Use build_segment to create the cohort in natural language. Be specific — include the behaviour, page/element if relevant, and time window.
Examples:
- "Users who saw the 'no cars found' modal in the last 30 days"
- "Users who rage clicked on the Add to Cart button on the product page in the last 30 days"
- "Users who reached the billing page but did not reach the checkout success page in the last 30 days"
- "Users who experienced a checkout payment error in the last 30 days"
The segment is saved automatically. Note the segment_id and segment_url.
Step 4 — Size and characterise the cohort
Run these in parallel:
get_opportunities(segment_id=<id>, time_range="30d")— What issues are disproportionately affecting this cohort vs the general population?get_sessions(segment_id=<id>, limit=10)— A sample of sessions to read.
From the opportunities, note: which issues are uniquely elevated for this cohort vs baseline? This tells you what the cohort has in common beyond the behaviour you targeted.
Step 5 — Read sessions
Pick 3–4 sessions from the sample. For each, call get_session_events(device_id=..., session_id=...).
Look for patterns across sessions:
- Where do they all enter? (same page, same device type, same referrer pattern?)
- What do they do before the friction point?
- What happens after — do they retry, abandon, or find a workaround?
- Is there a common error, element, or flow step that appears in most sessions?
Step 6 — Deliver the portrait
Write a cohort portrait structured as:
[Cohort name — give it a plain-English label, e.g. "Checkout abandoners at billing" or "Search dead-end users"]
Who they are: [2–3 sentences. What behaviour defines them. How many users in the last 30 days. What they were trying to do.]
What they experience: [2–3 sentences describing the shared pattern from session evidence. Concrete and specific — what screen, what happens, how they react.]
What sets them apart: [Issues or frustrations that are disproportionately elevated for this cohort vs all users — from the opportunity data. "These users are 3× more likely to see X than the average user."]
Why this matters: [Business impact framing. If they're checkout abandoners, estimate the revenue implication. If they're rage clickers, note the scale.]
What to do next:
- [Specific recommendation — e.g. "Investigate the /v2/cars/getAllCarsInOrgInCity 404 errors which appear in 80% of these sessions"]
- [Optional second recommendation]
Segment saved: [segment_url] — share this link to let anyone explore this cohort in Fullstory.
Session replays:
- [session_url] — [one-line description]
- [session_url] — [one-line description]
- [session_url] — [one-line description]
Naming the cohort
Give the cohort a name the business user would recognise — not "segment_abc123" but something like "Search dead-end users", "Blocked checkout guests", or "Mobile payment failures". The name should describe the experience, not the technical filter.