Get Funnel

Multi-step conversion funnel with per-step user counts, conversion ratios, and median time-to-convert.

GET /v0/funnel

Get multi-step conversion funnel

cURL

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

200

{
  "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–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 windowFunnel 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 via windowFunnel. open: unordered per-step minIf; 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

200

application/json

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

Show child attributes

rows · integer

rows_before_limit_at_least · integer

statistics · object