Saved event funnels

A saved funnel measures a journey with events you already collect. It is useful for flows such as a product view → checkout → payment, an onboarding sequence, or a support-to-conversion path. It is not the older reaction-only funnel in the Analytics overview: a saved funnel works with the shared event vocabulary.

Build a funnel

Open Analytics → Funnels and create a funnel with two to twenty steps. Give each step a clear name and choose one or more alternative event names. One matching alternative completes that step.

You can also add a condition on event properties, an audience segment, and an identity filter. These use the same approved event, condition, and segment vocabulary as the rest of the product. A property path cannot be entered as an arbitrary expression.

The order is strict: a customer reaches step 2 only after reaching step 1, and so on. If the events arrive at the same instant, their durable event order decides the sequence. An event that happened before the previous step does not complete the funnel.

Time, identity, and audience

Every report has an inclusive from and exclusive to UTC boundary. Choose a range of no more than 366 days. You can additionally set a conversion window from one minute to 366 days; a later step outside that window is not counted.

The report works on canonical customer identities. When profiles are merged, their events are evaluated as one customer where the event source supports the canonical identity. Anonymous events follow the funnel's identity filter and are not silently turned into a known person.

Segment membership is read from the currently published segment at report time. It is not a historical snapshot, so a segment changing today can change which customers qualify for a report requested today. The report range remains fixed while that audience rule is current.

Choose the conversion mode deliberately:

  • All currently keeps the first valid conversion for a customer, the same result as First. It remains available for compatibility; a distinct every-progression aggregation is not available yet.
  • First keeps the first valid conversion for a customer.
  • Repeat records repeat valid conversions after the first, but they are not reflected in the visible report yet. Counters, metrics, breakdowns, and cohorts use one best progression per customer regardless of the selected mode. Treat Repeat as a compatibility setting, not a multiple-conversion report.

Read the report

Each step shows the number of customers, conversion from the first step and from the previous step, drop-off, and median time since the previous step. A configured property breakdown returns at most 25 named values plus Other, so a high-cardinality property cannot create an unbounded report.

The UTC trend has continuous daily buckets that span exactly the requested [from, to) range. Its first, partial bucket starts at from; later buckets start at UTC midnight. Empty buckets contain zeroes.

Warnings are deterministic data-quality signals, not statistical-significance claims. zero_denominator means that no visitor reached the first step, so conversion rates are unavailable. high_cardinality_truncated means that breakdown values were grouped into Other after the 25-value limit. There is no partial_data warning. A zero denominator is shown as zero rather than as a misleading percentage.

Cohorts and segments

Select a step count to open its cohort. You can inspect canonical customer summaries and page through the results with a cursor; raw sensitive event properties are not exposed in the cohort drawer.

You can save a completed or dropped cohort as a dynamic segment. The segment stores the funnel ID, immutable revision, step, bounded date range, and an optional approved breakdown filter. It does not save a one-time list of customer IDs. Recomputing that segment evaluates the recorded funnel revision again.

Revisions and safe editing

Saving an edit creates the next funnel revision. Reports and cohort segments can keep using an earlier revision, so historical analysis remains readable. If someone else saves first, reload or clone the funnel instead of overwriting their revision. You can clone, archive, or delete a funnel. Deletion is refused when another supported object still references it.

API example

Use a personal access token with analytics:read for a report. Values below are placeholders, not real customer data or credentials.

curl -X POST "$BASE_URL/api/bots/$BOT_ID/funnels/$FUNNEL_ID/query" \
  -H "Authorization: Bearer $PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "revision": 3,
    "from": "2026-07-01T00:00:00Z",
    "to": "2026-08-01T00:00:00Z"
  }'

A stale edit returns 409 with funnel revision conflict; an invalid or unbounded range returns 400 or 422 depending on where validation fails. For a cohort request, send the same bounded range plus step_position, completed, limit, and the returned cursor on the next page. Creating a cohort segment additionally needs segments:write.

Related pages