# User journeys

Common paths users take through your agent — aggregated flow patterns, not single sessions.

The **User Journeys** page zooms out from individual sessions to show the *common paths* users take through your agent. It answers product questions: what's the typical flow? Where do people drop off? Which sequences end well, and which don't?

## What it is

A **journey** is an aggregated pattern — a sequence of user actions, agent responses, or intent transitions — that many sessions follow. Sessions show you one conversation; journeys show you the shape of all conversations.

Journeys are useful when you want to talk about behavior at the population level: "30% of new users start with intent X, and half of them never reach intent Y."

## How it's computed

Journey analysis is heavy, so it runs as a background workflow over a chosen time window (24h, 7d, 30d). The pipeline:

1. **Builds a sequence per session** — the ordered list of user turns, agent turns, or matched intents (depending on the journey type).
2. **Aligns and clusters** — sequences that share subsequences are grouped using sequence alignment + clustering.
3. **Summarizes each pattern** — Brizz writes a human-readable label and counts how many sessions follow it.

Because the job is expensive, journeys don't update in real time — kick off a compute when you want a fresh view.

## How to read it in the dashboard

The Journeys page is organized as a list of journey cards, ranked by the number of sessions that follow each pattern:

- **Steps** — the ordered sequence of intent labels or actions in this journey.
- **Volume** — how many sessions matched.
- **Outcome distribution** — for journeys where outcomes are defined (success/failure/dropoff), the split across them.
- **Sample sessions** — open a sample to see the actual conversation behind the pattern.

Pick a time range that matches your question. A 7-day window is the right default; 24h is too noisy, 30d smooths out recent regressions.

## How to act on it

1. **Find the "happy path" first.** The highest-volume journey with a successful outcome is your baseline — design and content should be optimized for it.
2. **Look at dropoff points, not endpoints.** Sessions ending mid-journey are a UX problem; sessions reaching the end with a bad outcome are a content problem.
3. **Compare two windows.** A journey that vanished after a deploy means you broke a flow; a new pattern that appeared often signals an unintended use case.
4. **Cross-check with Intents.** A journey that always starts with a specific intent and ends badly tells you exactly which prompt to fix.
5. **Don't optimize for rare paths.** A journey followed by 30 sessions out of 10,000 is a curiosity, not a roadmap item.

## See also

- [User intents](/docs/platform/user-intents.md) — the building blocks each journey is composed of.
- [Sessions](/docs/platform/sessions.md) — drill into the actual conversations behind a journey.
- [Issues](/docs/platform/issues.md) — when a journey reliably ends badly, the matching content/product issue is where to track the fix.