Measure bounded session paths

Paths measure what resolved people did around one event, inside the same session: which nodes followed it (forward) or led to it (backward), up to a bounded number of steps and a bounded time horizon. It answers a narrower, more precise question than a funnel — "what happens after checkout_started?" rather than "did people complete an ordered sequence?" — by walking every qualifying session once and reporting exactly what it found.

Your agent runs the measurement through MCP or the CLI. You open the stored result as a read-only proof page.

Ask your agent

"What do people do in the 30 minutes after checkout_started, in the same session? Measure the last 7 days and send me the proof link."

"Take the busiest edge in that result and list the exact sessions behind it, with their replay evidence."

Job	MCP tool or action	CLI command
Check which path shapes and bounds the server accepts	get_product_query_capabilities	anectico analytics capabilities
Measure paths around one anchor event	query_product_analytics	anectico analytics query
Read a stored paths result again	get_analytics_result	anectico analytics result get
Page the exact walked instances behind an edge	list_analytics_path_instances	anectico analytics result path-instances
Page the resolved people behind an edge	list_analytics_participants	anectico analytics result participants

These are MCP read actions. Your agent finds them with list_read_actions and runs them with execute_read_action. Measuring needs analytics:query, analytics:read and persons:read; reading the instances and the people needs analytics:read and persons:read; over MCP the key also needs mcp:read. Reading page-path node keys needs the content read permission (see Define a measurement).

What your agent gets back

The response carries paths.manifest, state, summary, steps, edges, other, and the two selection registries described below. Every count keeps occurrences, instances and people apart (see Read the counts). Every displayed edge declares an instances_selection_id and a people_selection_id, which your agent pages with the last two tools in the table.

Over MCP, the result carries a link to the proof page in its links, in the entry titled "Analytics result" (the address is its href). Every tool in the table that reads this stored result carries the same link. The CLI prints the result and no link.

Open the proof

Open the link from your agent. It opens the stored result in the read-only result viewer, with the project named in the page header. See Proof pages and Result viewer.

The page never measures again. It shows what was stored, when it was measured (in UTC) and when the stored result expires. Its one action is Copy link. To change the question, ask your agent to measure again with a new definition and a new execution key.

You see:

• a state banner, then the summary, including the terminal breakdown and excluded_no_session;
• one bar per step, showing its node breakdown with other folded in;
• the edge table described below. An edge's instances count opens the walked paths behind it — timestamps, the highlighted transition step, the terminal and the replay reference — and its people count opens the resolved people behind it.

What one path instance is

For each (subject, session), a path instance starts at the first anchor occurrence inside the measurement window. Anchor occurrences that carry no session ID are never stitched to anything; they are counted in the summary's excluded_no_session and never become an instance.

From the anchor, the walk follows the same subject's events of the same session only — never another session, even the same person's — for up to transitions steps, within horizon_minutes of the anchor. Forward reads follow-up after the anchor; backward reads history before it, and that history must be inside your retained, readable window or the measurement fails HISTORY_UNAVAILABLE.

Define a measurement

{
  "version": 2,
  "timezone": "UTC",
  "window": {"relative": {"lookback_seconds": 604800}},
  "paths": {
    "anchor": {"name": "checkout_started"},
    "direction": "forward",
    "transitions": 2,
    "horizon_minutes": 30,
    "node_key": "event"
  }
}

Run it the same way as any other kind: anectico --project PROJECT_UUID analytics query --file paths.json --execution-key EXECUTION_UUID, MCP's query_product_analytics, or POST /api/v1/analytics/query.

• anchor is exactly one event selector, with its own event-property filters if you need them — a path's nodes are every event of the anchor's own session, so an event predicate belongs on the anchor, never at the top level. Person-property filters, cohorts and environment restrict which subjects can anchor a path, the same way they do for any other kind.
• direction is forward (what happened after the anchor) or backward (what led to it).
• transitions is 1 to 4 steps.
• horizon_minutes is 1 to 30; omitted or 0 normalizes to 30.
• node_key is event (the default) or event_and_path, which additionally keys a $pageview node by its sanitized route — an invalid route keeps an empty page for that node, it never falls back to a different key. Reading page-path node keys needs the content read permission; without it, a request naming event_and_path is refused the same way a missing permission refuses anything else.

Paths are person-unit only (QUERY_UNIT_UNSUPPORTED for the account unit) and accept event filters on the anchor only: a breakdown, a comparison window, a top-level event filter, a filter_group, or an account filter is refused with QUERY_PATHS_INVALID, as is a missing or unknown direction/node key, a missing anchor, or zero transitions. More than 4 transitions or 30 horizon minutes is QUERY_PATHS_LIMIT. anectico analytics capabilities (or the equivalent MCP/REST discovery call) reports the kind with path_directions, path_node_keys, and every max_path_* bound — a shape it does not list is refused before anything runs.

How the walk decides what happened

A repeat of the node you are already on is absorbed — it is examined, but it is never a transition, so three page views of the same route in a row are one node, not three. Events that land at the exact same millisecond and name more than one distinct node cannot be ordered: no guess is made, and the walk stops there with the terminal ambiguous_order. A tie of otherwise identical events at the same millisecond — the same node reached twice at once — is not ambiguous; it is a repeat, absorbed the same way any other repeat is.

Every instance ends in exactly one of six terminals, and the six always sum to the total instance count:

Terminal	Meaning
continues_beyond_limit	The walk used every allowed transition, and the session shows a further transition inside the horizon.
session_end	No further event of the session inside the horizon after the last transition.
horizon	The session continued inside the horizon, but only repeating the current node — the horizon, not the session, ended the walk.
ambiguous_order	A same-millisecond tie of different nodes stopped the walk.
truncated	The instance examined the platform's bounded event budget without a decided terminal.
immature	A forward instance whose horizon had not closed at the moment the result was measured — never a fabricated session_end. Backward paths, which only read history, are never immature.

state on the result reflects what could be established: measured (every terminal decided), partial (at least one instance is immature — its path may still grow when you measure again), insufficient_evidence (coverage of the scanned span was not sufficient — counts are disclosed as observed), or unavailable (platform coverage could not be established at all — nothing is disclosed: no summary, no steps, no edges, no selections).

Read the counts: occurrences, instances, and people are never the same number

Every count in a paths result keeps three things apart, on purpose:

• occurrences — every time an instance made a transition. A loop (A→B→A→B) makes the A→B transition twice, so its occurrences are 2.
• instances — distinct walked paths. The same loop is still one instance.
• people / unresolved — distinct resolved people, and distinct unresolved identities, among those instances, kept separate and never merged.

steps[k] lists the nodes instances reached at walk distance k (k=0 is the anchor itself), ranked by instances, then event and page. Only the most frequent nodes are shown per step; the rest are folded into that step's other, which discloses how many distinct nodes were omitted and how many instances they account for — the displayed nodes plus other always partition the step's reach exactly.

edges lists the displayed transitions, time-ordered from → to whatever the walk direction, with occurrences, instances, and people/unresolved kept separate as above. other is the deduplicated union of every transition not displayed: its occurrences is a sum (loops still add), but its instances and people count each contributing instance and person once, even if that instance made two different omitted transitions. The proof page labels this row "Other · union, deduplicated" for exactly that reason — it is not the sum of the omitted edges' individual counts.

Page the exact walked instances, with replay evidence

Every displayed edge (and other, when it has omitted edges) declares an instances_selection_id. Page it — 1 to 50 at a time — with anectico analytics result path-instances RESULT_UUID --selection-id SELECTION_UUID, MCP's list_analytics_path_instances, or GET /api/v1/analytics/results/{id}/path-instances. Each instance is one frozen walked path:

• path_instance_id — stable across reads of the same instance, and never a person or participant ID.
• contributor, session_id, anchor_time, and terminal.
• events — the walked nodes in walk order (the anchor at step 0, then the first event of each transition), each with its own timestamp.
• edge_steps — the transition steps at which this selection's edge (or, for other, any omitted edge) occurs in this instance; a loop lists more than one.
• replay — always present, because every instance has a session ID: available opens the recording, none_recorded is an honest absence (a session that was never recorded), and withheld means your current credential cannot read session replay. Treat withheld as a permissions gap, never as proof nothing was recorded — the proof page's instance panel never collapses the two.

An instance selection is a page of walked paths, not a population of people: it cannot become an audience and does not page through the participants endpoint.

People and audiences

Every displayed edge (and other) also declares a people_selection_id: the distinct resolved people who made that transition, an ordinary resolved-people population. Page it with anectico analytics result participants, the equivalent MCP call (list_analytics_participants), or the REST participants route, and create an audience from it exactly the way you would from any other kind's selection (create_analytics_audience, or anectico analytics audiences create).

What paths cannot do

A paths result is a graph of selections, not the one scalar or row stream some other operations need:

• A metric watch refuses a paths definition outright (UNSUPPORTED_RESULT_SELECTOR).
• A Live panel refuses to render a paths result the same way.
• An export of a paths result is refused: its evidence is the instance pages above, which an export does not carry. Page the walked instances to review that evidence.
• analytics result contribution has no drill-down chain for paths either — the instance pages above are the evidence, not a separate contribution read.

A saved insight of a paths definition, and a dashboard widget bound to one, render normally: the widget shows the same state, summary, and step/edge shapes described above.