Skip to main content
GET
/
v0
/
funnel
Get multi-step conversion funnel
curl --request GET \
  --url https://api.formo.so/v0/funnel \
  --header 'Authorization: Bearer <token>'
{
  "meta": [
    {
      "name": "step",
      "type": "UInt64"
    },
    {
      "name": "event",
      "type": "String"
    },
    {
      "name": "users",
      "type": "UInt64"
    },
    {
      "name": "total",
      "type": "UInt64"
    },
    {
      "name": "conversion_from_start",
      "type": "Nullable(Float64)"
    },
    {
      "name": "conversion_from_previous",
      "type": "Nullable(Float64)"
    },
    {
      "name": "dropoff_from_previous",
      "type": "Nullable(Float64)"
    },
    {
      "name": "median_seconds_from_previous",
      "type": "Nullable(Float64)"
    },
    {
      "name": "median_seconds_from_start",
      "type": "Nullable(Float64)"
    }
  ],
  "data": [
    {
      "step": 1,
      "event": "page::0",
      "users": 1240,
      "total": 1240,
      "conversion_from_start": 1,
      "conversion_from_previous": null,
      "dropoff_from_previous": null,
      "median_seconds_from_previous": null,
      "median_seconds_from_start": null
    },
    {
      "step": 2,
      "event": "connect::1",
      "users": 482,
      "total": 482,
      "conversion_from_start": 0.3887,
      "conversion_from_previous": 0.3887,
      "dropoff_from_previous": 0.6113,
      "median_seconds_from_previous": 38,
      "median_seconds_from_start": 38
    },
    {
      "step": 3,
      "event": "swap::2",
      "users": 187,
      "total": 187,
      "conversion_from_start": 0.1508,
      "conversion_from_previous": 0.388,
      "dropoff_from_previous": 0.612,
      "median_seconds_from_previous": 124,
      "median_seconds_from_start": 162
    }
  ],
  "rows": 3,
  "rows_before_limit_at_least": 3
}
Returns the same funnel data the dashboard renders on the Funnels page. For an ordered list of step specs, you get 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. Use funnel_type=closed (default) for ordered, in-window conversions (the default that powers the dashboard) or funnel_type=open to count whoever fired step k regardless of order - open mode also returns a dropped_off_users column. Set breakdown to a dimension (device, browser, os, location, referrer, or any UTM column) to group each step by first-touch attribution; breakdown_top_n controls how many categories are kept before bucketing the rest as Others.

​
Defining steps

The steps query parameter is a JSON-encoded array of 2–10 step specs. Each step is {type, event, name, filters?: [...]}:
  • type - event type (event for page views, track for custom events, transaction, signature, decoded_log).
  • event - the event name to match.
  • name - a unique step id. Use <event>::<index> (e.g. "connect::1") so the same event re-used at multiple steps can be told apart in the response.
  • filters - optional [{operand, operator, value}].
    • Operators:
      • equals
      • notEquals
      • in
      • notIn
      • gt
      • lt
      • gte
      • lte
      • startsWith
      • endsWith
      • includes
    • operand may target a standard event column or a JSON property on properties.

​
Example

curl -G "https://api.formo.so/v0/funnel" \
  -H "Authorization: Bearer $FORMO_API_KEY" \
  --data-urlencode "dateFrom=2026-04-01" \
  --data-urlencode "dateTo=2026-04-30" \
  --data-urlencode "window_seconds=86400" \
  --data-urlencode 'steps=[
    {"type":"event","event":"page","name":"page::0","filters":[]},
    {"type":"track","event":"connect","name":"connect::1","filters":[]},
    {"type":"track","event":"swap","name":"swap::2","filters":[{"operand":"chain","operator":"equals","value":"ethereum"}]}
  ]'

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 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.

​
date_to
string<date>
required

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

​
steps
string
required

JSON-encoded array of 2 to 10 step specs. Each step is {type, event, name, filters?: [{operand, operator, 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: equals, notEquals, in, notIn, gt, lt, gte, lte, startsWith, endsWith, includes. For in/notIn, 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).

​
window_seconds
integer
default:1209600

Conversion window length in seconds. Defaults to 1,209,600 (14 days). For closed funnels this is the in-order completion cap; for both variants the events scan is extended by this amount past date_to.

Required range: x >= 1
​
funnel_type
enum<string>
default:closed

closed (default): ordered, in-window. open: unordered per-step; emits an extra dropped_off_users column.

Available options:
closed,
open
​
breakdown
enum<string>

Optional dimension to break each step down by (first-touch attribution). When set, the response gains a breakdown column.

Available options:
device,
browser,
os,
location,
referrer,
utm_source,
utm_medium,
utm_campaign,
utm_content,
utm_term
​
breakdown_top_n
integer
default:8

Top-N breakdown categories to keep (by user count). Remaining categories are bucketed as Others. Defaults to 8.

Required range: x >= 1

Response

Per-step funnel results

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