Funnel Analytics

Funnels

Funnel Analytics V2 with strict canonical steps, single endpoint contract, and actionable drop-off insights.

Audience: Growth and e-commerce teams optimizing conversion paths.

Critical: Funnel V2 is breaking: only GET /api/v1/analytics/funnels/:siteId is supported. Legacy /analytics/funnel/* endpoints are removed.

Funnel Definitions Journeys Event Sequences

Who This Page Is For

Use this page when you need strict ordered funnel conversion analysis with clear step-level drop-off diagnosis.

Quick Start (2-5 Minutes)

Run core checkout funnel

Analyze product -> cart -> checkout -> purchase with strict order.

GET /api/v1/analytics/funnels/SITE_ID?steps=product_view,add_to_cart,checkout_begin,purchase&mode=hybrid

Run search-to-purchase funnel

Measure search intent conversion quality.

GET /api/v1/analytics/funnels/SITE_ID?steps=search_query,product_click,add_to_cart,purchase

Scope by period

Limit analysis window with ISO date filters.

GET /api/v1/analytics/funnels/SITE_ID?steps=product_view,add_to_cart,purchase&startDate=2026-02-01&endDate=2026-02-15

Switch flow key mode

Use journey-only grouping when required.

GET /api/v1/analytics/funnels/SITE_ID?steps=product_view,add_to_cart,purchase&mode=journey

Use saved definition analyze endpoint

Analyze saved funnels through the same V2 response contract.

GET /api/v1/analytics/funnels/definitions/:id/analyze?mode=hybrid

Funnel V2 endpoint

GET /api/v1/analytics/funnels/:siteId

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`siteId`	Required	`uuid (path)`	funnel v2 endpoint	Site scope for analysis.
`steps`	Required	`comma-separated canonical events`	funnel v2 endpoint	Strict ordered events. Must be 2-8 unique canonical names.
`mode`	Optional	`hybrid \| journey`	funnel v2 endpoint	Flow grouping key strategy. Default: hybrid.
`startDate / endDate`	Optional	`ISO date`	funnel v2 endpoint	Date range filter for events.

Response Contract (V2)

Response shape

{
"meta": {
  "siteId": "...",
  "mode": "hybrid",
  "dateRange": { "startDate": "...", "endDate": "..." },
  "totalFlows": 0,
  "scannedEvents": 0
},
"summary": {
  "entries": 0,
  "conversions": 0,
  "overallConversionRate": 0,
  "totalDropoff": 0,
  "biggestDropoffStep": null
},
"steps": [
  {
    "stepOrder": 1,
    "eventName": "product_view",
    "count": 0,
    "fromStartPercent": 0,
    "stepConversionPercent": 100,
    "dropoffCount": 0,
    "dropoffPercent": 0
  }
],
"insights": []
}

UI Information Modals (Dashboard)

How Funnel Is Calculated: strict order, flow key behavior (hybrid vs journey), formula definitions.
Template Guide: what each core template is designed to answer and misuse warnings.
How To Read Metrics: definitions for From Start, Step Conversion, Drop-off.
Comparison Methodology: previous-period logic and interpretation boundaries.

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Need checkout drop-off diagnosis	/analytics/funnels/:siteId?steps=product_view,add_to_cart,checkout_begin,purchase	Core e-commerce path quality.
Need search conversion context	/analytics/funnels/:siteId?steps=search_query,product_click,add_to_cart,purchase	Tracks search intent to purchase.
Need recommendation conversion context	/analytics/funnels/:siteId?steps=widget_impression,click,add_to_cart,purchase	Widget exposure to purchase flow.
Need campaign pipeline context	/analytics/funnels/:siteId?steps=impression,click,add_to_cart,purchase	Campaign conversion efficiency.
Need reusable funnel definitions	/analytics/funnels/definitions*	Saved templates + V2 analyze + exports.

Common Errors and Fixes

400: Funnel steps must include between 2 and 8 events

Cause: steps has too few or too many items.

Fix: Provide 2-8 canonical events in strict order.

400: Duplicate funnel steps are not allowed

Cause: steps includes repeated event names.

Fix: Use unique event names in the steps query.

400: Funnel steps must be provided as a single comma-separated string

Cause: steps sent as repeated query params or non-CSV format.

Fix: Send one steps value, e.g. steps=product_view,add_to_cart,purchase.

400: Unsupported funnel step events

Cause: Non-canonical event names used.

Fix: Use canonical events from tracking contract only.

Very high delta in comparison mode

Cause: Low sample sizes between periods.

Fix: Validate absolute counts before acting on percentage deltas.

Production Checklist

All funnel calls use /analytics/funnels/:siteId only.Required
Preset templates are mapped to canonical event names.Required
steps validation is enforced as 2-8 unique canonical events.Required
Comparison interpretation includes sample-size checks.Required
Teams use info modals to standardize metric interpretation.Required