Funnels

Define ordered conversion funnels over your event stream and measure per-step progression, conversion rate, and drop-off within a conversion window.

A funnel is a saved, ordered sequence of steps. Each step is an event name plus an optional set of property filters. Amba computes how many distinct users progressed through each step — and where they dropped off — within a conversion window.

Funnels build directly on the Analytics event stream: every Amba.events.track(name, properties) call is a row a funnel can match against. There's nothing new to instrument — if you're already tracking events, you can define a funnel over them today.

Funnels are an admin / analytics surface: you create and query them from the Admin API or MCP tools, the same way you manage segments. There is no client-SDK call for funnels — your app keeps calling events.track, and funnels are computed server-side on demand.

Anatomy of a funnel

{
  "name": "Signup → Subscribe",
  "description": "Onboarding conversion",
  "conversion_window_seconds": 604800,
  "steps": [
    { "event": "app_open" },
    {
      "event": "signup_started",
      "filters": [{ "property": "source", "op": "eq", "value": "organic" }]
    },
    { "event": "subscription_started" }
  ]
}

steps — an ordered array of 2–10 steps. Step order is the funnel order.
event — the event name to match for that step.
filters — optional property predicates, ANDed together. An event only matches the step if it satisfies every filter.
conversion_window_seconds — how long a user has, from their first step-1 event, to complete the remaining steps. Defaults to 604800 (7 days). Bounded to 1 minute … 90 days.

Step filters

Each filter is { property, op, value }. property is a dot-path into the event's properties (e.g. source, plan.tier). Supported operators:

Operator	Meaning	`value`
`eq` / `neq`	equals / not-equals	string, number, or boolean
`gt` / `gte` / `lt` / `lte`	numeric comparison	number
`contains` / `not_contains`	case-insensitive substring	string
`exists` / `not_exists`	property present / absent	— (omit `value`)

A missing property satisfies neq, not_contains, and not_exists; it never satisfies eq, contains, or a numeric comparison.

Windowing & ordering semantics

These are the defaults Amba applies. Understanding them is the difference between a funnel you trust and one you don't:

Ordered. A user is credited with step N only if they emitted step N at or after their matched step N−1 event. Out-of-order events don't count. (Comparison is non-strict, so two events recorded in the same batch with identical timestamps still progress.)
First-match-after-prior. For each step, Amba takes the earliest qualifying event that occurs at or after the previous step's matched time. This is the standard greedy match.
Windowed from entry. The conversion window is anchored at the user's first qualifying step-1 (entry) event inside the query's [from, to) range. Every later step must occur within entry + conversion_window_seconds.
The window may extend past to. A user who entered near the end of the date range still gets their full window to convert — later steps are bounded by their personal window, not by to. (Corollary: if you set to to "now", recently-entered users whose window hasn't elapsed yet may still convert, so a fresh query can understate conversion for the latest cohort.)
User-level counts. Each step count is the number of distinct users who reached it, not raw event counts. Counts are monotonically non-increasing across steps.

Creating a funnel

amba_funnels_create
  project_id: "proj_…"
  name: "Signup → Subscribe"
  conversion_window_seconds: 604800
  steps: [
    { event: "app_open" },
    { event: "signup_started", filters: [{ property: "source", op: "eq", value: "organic" }] },
    { event: "subscription_started" }
  ]

The other CRUD operations follow the same shape: amba_funnels_list, amba_funnels_get, amba_funnels_update, amba_funnels_delete (REST: GET/PATCH/DELETE /v1/admin/projects/:projectId/funnels/:funnelId).

Querying a funnel

Query a saved funnel over an entry date range. from/to (ISO-8601) bound which entry events count; they default to the last 30 days.

amba_funnels_query
  project_id: "proj_…"
  funnel_id: "fnl_…"
  from: "2026-05-01T00:00:00Z"   # optional, defaults to 30 days ago
  to:   "2026-05-28T00:00:00Z"   # optional, defaults to now

Result shape

{
  "data": {
    "funnel_id": "fnl_…",
    "name": "Signup → Subscribe",
    "conversion_window_seconds": 604800,
    "from": "2026-05-01T00:00:00.000Z",
    "to": "2026-05-28T00:00:00.000Z",
    "total_entered": 1000,
    "total_converted": 120,
    "overall_conversion_rate": 0.12,
    "steps": [
      {
        "index": 0,
        "event": "app_open",
        "filters": [],
        "users": 1000,
        "conversion_rate": 1,
        "conversion_from_previous": 1,
        "dropped_off": 0,
        "drop_off_rate": 0
      },
      {
        "index": 1,
        "event": "signup_started",
        "filters": [{ "property": "source", "op": "eq", "value": "organic" }],
        "users": 400,
        "conversion_rate": 0.4,
        "conversion_from_previous": 0.4,
        "dropped_off": 600,
        "drop_off_rate": 0.6
      },
      {
        "index": 2,
        "event": "subscription_started",
        "filters": [],
        "users": 120,
        "conversion_rate": 0.12,
        "conversion_from_previous": 0.3,
        "dropped_off": 280,
        "drop_off_rate": 0.7
      }
    ]
  }
}

Per-step fields:

users — distinct users who reached this step.
conversion_rate — users / total_entered (share of all entrants who got this far).
conversion_from_previous — users / previous step's users (step-to-step conversion).
dropped_off — how many users present at the previous step did not advance.
drop_off_rate — dropped_off / previous step's users.

overall_conversion_rate is total_converted / total_entered — the share of entrants who completed the whole funnel.