Skip to main content
GET
Get session-scoped user-flow transitions (Sankey)
Returns the same Sankey transitions the dashboard renders on the Flows chart. For each session that fires the start step inside [date_from, date_to], the pipe rebuilds the ordered sequence of subsequent events within the conversion window, normalises them into flow-node labels, and emits one row per (step, source, target) transition with counts and per-step percentages. When end_step is set, only sessions that reached the end event within the conversion window are kept (converter-only mode), and the matched event is suffixed with __END_MATCH__.

Defining start and end steps

Both start_step and end_step are JSON-encoded objects of shape {type, event, resolved_event, filters?: [...], status_type?, status_value?}:
  • type - event type (event, track, transaction, signature, decoded_log).
  • event - the event name.
  • resolved_event - the value matched against the events table. Use the sentinel "__ALL_PAGE_VIEWS__" to match any page view, or the page path / event name otherwise.
  • filters - optional [{field, op, value, values?}]. Use values for the in / nin operators. Operators use the canonical tokens only (eq, neq, in, nin, gt, lt, gte, lte, startsWith, endsWith, contains, notEmpty, isEmpty). Retired long-form spellings like equals / notIn / includes are rejected with a 400 naming the token.
Pass global_filters as a JSON-encoded array to apply additional {field, op, value, values?} constraints to both the start-session scan and the relevant-events scan.

Conversion window and depth

window_seconds (default 7200, or 2 hours) bounds how long after the start event the path is allowed to extend. max_steps (default 4, clamped to 2..10) caps the Sankey depth.

Example

Authorizations

Authorization
string
header
required

Workspace API key (e.g. formo_xxx). Create one in the Formo dashboard under Team Settings > API.

Query Parameters

date_from
string<date>
required

Inclusive ISO date for the start of the start-event window (YYYY-MM-DD).

date_to
string<date>
required

Inclusive ISO date for the end of the start-event window (YYYY-MM-DD).

start_step
string
required

JSON-encoded start-step spec of shape {type, event, resolved_event, filters?: [...], status_type?, status_value?}. Use "resolved_event":"__ALL_PAGE_VIEWS__" to match any page view; pass a page path for a specific landing page; or pass an event name for track/decoded_log start events. filters use {field, op, value, values?} (use values for in/nin).

Filter operators: eq, neq, in, nin, gt, lt, gte, lte, startsWith, endsWith, contains, notEmpty, isEmpty (canonical tokens only; the retired long-form spellings equals/greater/includes/… are rejected, notEmpty/isEmpty are value-less existence checks, rejected on numeric event columns volume/revenue/points). Standard columns (device, browser, os, location, referrer, utm_*, page_path, etc.) are read directly; everything else is read from properties via JSONExtractString (or JSONExtractFloat for numeric comparators).

end_step
string

Optional JSON-encoded end-step spec, same shape as start_step. When present, paths are truncated at the first end-event match (suffixed __END_MATCH__) and only converting sessions are returned.

global_filters
string

Optional JSON-encoded array of {field, op, value, values?} filters applied to both the start-session scan and the relevant-events scan. Useful for restricting the entire flow to a specific cohort (e.g. desktop visitors, a UTM source, a wallet provider).

window_seconds
integer
default:7200

Conversion window length in seconds. Defaults to 7,200 (2 hours).

Required range: x >= 1
max_steps
integer
default:4

Maximum number of transitions per session (Sankey depth). Clamped to 2..10.

Required range: 2 <= x <= 10

Response

Per-step Sankey transitions

Analytics endpoint response. The data array contains the rows; the exact row shape depends on the endpoint. meta carries column type information for rendering, rows is the row count, and statistics holds query timing metadata.

data
object[]
meta
object[]
rows
integer
rows_before_limit_at_least
integer
statistics
object