Query

Get session-scoped user-flow transitions (Sankey)

Session-scoped user-flow transitions for Sankey-style charts. Given a required start_step, optional end_step, date window, conversion window, and max-step cap, returns one row per (step, source, target) transition with counts and per-step percentages.

How it works: for each session that fires the start step inside [date_from, date_to], the endpoint rebuilds the ordered sequence of subsequent events within the conversion window (window_seconds), normalises each event into a flow-node label (page path for page, event name for track/decoded_log, prefixed for signature/transaction), truncates at the first end-step match (when end_step is set), and slices to max_steps + 1 nodes. Adjacent nodes are then exploded into (step, source, target) edges with counts and percentages.

Converter-only mode: when end_step is set, only sessions that actually reached the end event within the window are kept, and the matched event is suffixed with __END_MATCH__. This mirrors PostHog’s pathsFilter.endPoint behaviour; every visible link is part of a converting path.

Step shape: start_step and end_step are JSON objects of shape {type, event, resolved_event, filters?: [...], status_type?, status_value?}. resolved_event is the value used to match against the events table (event name, page path, or the sentinel __ALL_PAGE_VIEWS__ for any page view). filters and global_filters accept {operand, operator, value, values?} (use values for in/notIn).

GET

flow

Get session-scoped user-flow transitions (Sankey)

curl --request GET \
  --url https://api.formo.so/v0/flow \
  --header 'Authorization: Bearer <token>'

{
  "meta": [
    {
      "name": "step",
      "type": "UInt32"
    },
    {
      "name": "source",
      "type": "String"
    },
    {
      "name": "target",
      "type": "String"
    },
    {
      "name": "transitions",
      "type": "UInt64"
    },
    {
      "name": "percentage",
      "type": "Float64"
    }
  ],
  "data": [
    {
      "step": 1,
      "source": "/",
      "target": "/swap",
      "transitions": 412,
      "percentage": 47.83
    },
    {
      "step": 1,
      "source": "/",
      "target": "/earn",
      "transitions": 248,
      "percentage": 28.79
    },
    {
      "step": 2,
      "source": "/swap",
      "target": "connect",
      "transitions": 198,
      "percentage": 38.6
    },
    {
      "step": 3,
      "source": "connect",
      "target": "swap__END_MATCH__",
      "transitions": 112,
      "percentage": 56.57
    }
  ],
  "rows": 4,
  "rows_before_limit_at_least": 4
}

Authorizations

Authorization

string

header

required

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

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 {operand, operator, value, values?} (use values for in/notIn).

Filter operators: equals, notEquals, in, notIn, gt, lt, gte, lte, startsWith, endsWith, includes. 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 {operand, operator, 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:1209600

Conversion window length in seconds. Defaults to 1,209,600 (14 days).

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[]

Show child attributes

rows

integer

rows_before_limit_at_least

integer

statistics

object

Get multi-step conversion funnel

Ingest events

Get session-scoped user-flow transitions (Sankey)

curl --request GET \
  --url https://api.formo.so/v0/flow \
  --header 'Authorization: Bearer <token>'

{
  "meta": [
    {
      "name": "step",
      "type": "UInt32"
    },
    {
      "name": "source",
      "type": "String"
    },
    {
      "name": "target",
      "type": "String"
    },
    {
      "name": "transitions",
      "type": "UInt64"
    },
    {
      "name": "percentage",
      "type": "Float64"
    }
  ],
  "data": [
    {
      "step": 1,
      "source": "/",
      "target": "/swap",
      "transitions": 412,
      "percentage": 47.83
    },
    {
      "step": 1,
      "source": "/",
      "target": "/earn",
      "transitions": 248,
      "percentage": 28.79
    },
    {
      "step": 2,
      "source": "/swap",
      "target": "connect",
      "transitions": 198,
      "percentage": 38.6
    },
    {
      "step": 3,
      "source": "connect",
      "target": "swap__END_MATCH__",
      "transitions": 112,
      "percentage": 56.57
    }
  ],
  "rows": 4,
  "rows_before_limit_at_least": 4
}