---
title: "Get session-scoped user-flow transitions (Sankey)"
method: GET
path: "/v0/flow"
tags: ["Query"]
---

# Get session-scoped user-flow transitions (Sankey)

`GET /v0/flow`

## Request

- Base URL: `https://api.formo.so`
- URL: `https://api.formo.so/v0/flow`
- Auth: HTTP bearer

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 `{field, op, value, values?}` (use `values` for `in`/`nin`).

## Query parameters

- `date_from` string, date, required
- `date_to` string, date, required
- `start_step` string, required
- `end_step` string
- `global_filters` string
- `window_seconds` integer
- `max_steps` integer

## Response `200`

Per-step Sankey transitions

- AnalyticsResponse: 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[]
    - `name` string
    - `type` string
  - `rows` integer
  - `rows_before_limit_at_least` integer
  - `statistics` object

## Other responses

- `400`: Invalid `start_step`, `end_step`, or other query parameters
- `401`: Invalid API key
- `403`: Insufficient permissions

---

[API](https://skmtc.dev/formo/apis/formo-public-api.md) · [All operations](https://skmtc.dev/formo/apis/formo-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/formo/apis/formo-public-api/revisions/67ada57df63c?raw)