Get multi-step conversion funnel
Multi-step conversion funnel. For an ordered list of step specs, returns one row per step with the unique-user count, conversion ratios against step 1 and the previous step, drop-off ratio, and median time-to-convert (from-previous and from-start, in seconds).
Closed vs open: funnel_type=closed (default) requires the user to fire the steps in order within window_seconds. funnel_type=open counts whoever fired step k regardless of order, and adds a dropped_off_users column for each step.
Breakdown: when group_by is set to a column from the breakdown allowlist (device, browser, os, location, referrer, ref, utm_source, utm_medium, utm_campaign, utm_content, utm_term, builder_codes), the response gains a breakdown column and is grouped per (step, top-N category + 'Others', up to limit which defaults to 5). First-touch attribution is used by default; pass attribution=last_touch to bucket by each user's latest value.
Steps: the steps query param is a JSON-encoded array of 2 to 10 step specs of shape {type, event, name, filters?: [{field, op, value}]}. Use name (e.g. "page::0") as a unique step id so the same event re-used at different steps can be disambiguated in the response. op accepts eq | neq | in | nin | gt | lt | gte | lte | startsWith | endsWith | contains | notEmpty | isEmpty (canonical tokens only; the retired long-form spellings are rejected, notEmpty/isEmpty are value-less existence checks, rejected on the numeric event columns volume/revenue/points). field may target a standard event column or a JSON property on properties.
Request
- Base URL: https://api.formo.so
- URL: https://api.formo.so/v0/funnel
- Auth: HTTP bearer
Query parameters
Inclusive ISO date for the start of the funnel window (YYYY-MM-DD). The events scan extends past date_to by window_seconds so a user who fires step 1 just before date_to can still complete the funnel inside their conversion window.
Inclusive ISO date for the end of the start-event window (YYYY-MM-DD).
JSON-encoded array of 2 to 10 step specs. Each step is {type, event, name, filters?: [{field, op, value}]}. type is the event type (e.g. event for page views, track for custom events, transaction, signature, decoded_log). event is the event name. name is the unique step id (use "<event>::<index>" to disambiguate repeated events).
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). For in/nin, pass the values as a |-separated string in value (e.g. "ethereum|polygon|base").
Standard columns (rendered via direct column access): origin, device, browser, os, location, referrer, direct, ref, utm_source, utm_medium, utm_campaign, utm_content, utm_term, builder_codes, version, locale, timezone, page_path. Anything else is treated as a JSON property and read from properties via JSONExtractString (or JSONExtractFloat for numeric comparators).
Conversion window length in seconds. Defaults to 7,200 (2 hours). For closed funnels this is the in-order completion cap; for both variants the events scan is extended by this amount past date_to.
closed (default): ordered, in-window. open: unordered per-step; emits an extra dropped_off_users column.
Optional dimension to break each step down by. Defaults to first-touch attribution; pass attribution=last_touch to bucket by each user's latest value. When set, the response gains a breakdown column.
Top-N breakdown categories to keep (by user count), used only with group_by. Remaining categories are bucketed as Others. Defaults to 5.
Per-user attribution for the group_by dimension. first_touch (default) buckets each user by their earliest value; last_touch by their latest. Ignored unless group_by is set.
Response
Per-step funnel results
Changes
No recorded changes to this operation across all 1 revision of this API.