users.journey
Retrieve chronological session history for a single visitor to analyze multi-touch attribution or debug user journeys.
Instructions
Chronological session history for a single visitor (anonymous_id). Each session collapses to one row showing the start and end timestamps, entry page, channel, referrer host, UTMs, country, device type, pageview count, and the distinct custom event names fired in that session. The first row is flagged with is_first_touch: true.
Use this when an aggregate query can't answer the question — multi-touch attribution analysis, support / debugging investigations ("what did this user do before signing up?"), or sanity-checking a specific account's journey before drawing conclusions about a cohort.
Examples:
"show me what this user did across all their visits" → anonymous_id="anon_xxx"
"where did this paying customer first come from?" → anonymous_id="anon_xxx", read sessions[0].channel
"did they convert on their first visit or come back later?" → check if signup-event sessions match is_first_touch=true
Limitations: requires the visitor's anonymous_id, which the SDK exposes via getAnonymousId() on the browser side. Aggregate questions ("which channels drive my best users") use revenue.sum with attribution_model="first_touch" — don't loop this tool over thousands of users. Defaults to a 365-day lookback so first-touch is meaningful; tighten with period if needed.
Pairs with: revenue.sum(attribution_model="first_touch") to validate the aggregate first-touch read against specific high-value customers' actual paths.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| anonymous_id | Yes | The visitor's anonymous_id. From the browser SDK's getAnonymousId() / localStorage clamp_aid; from server-side tracks, whatever you passed as anonymousId. | |
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| limit | No | Max sessions to return. Defaults to 50, max 200. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| anonymous_id | Yes | ||
| sessions | Yes |