Funnel Definitions

Create reusable funnel definitions, analyze saved funnels, and export step/user results.

Audience: Analysts and growth teams maintaining repeatable funnel measurement assets.

Critical: All definition endpoints are under /api/v1/analytics/funnels/definitions* and export endpoints are under /api/v1/analytics/funnels/:siteId/*.

Funnels Event Sequences Journeys

Who This Page Is For

Use this page when your team repeatedly analyzes the same funnel and needs reusable definitions, templates, and export workflows.

Quick Start (2-5 Minutes)

Create definition

Save funnel steps and metadata for a site.

POST /api/v1/analytics/funnels/definitions

List definitions and templates

Fetch saved definitions and starter templates for site.

GET /api/v1/analytics/funnels/definitions/site/:siteId
GET /api/v1/analytics/funnels/definitions/site/:siteId/templates

Analyze saved definition

Run analysis using stored funnel definition with Funnel V2 response contract.

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

Duplicate and adjust

Clone a definition for variant analysis.

POST /api/v1/analytics/funnels/definitions/:id/duplicate

Export full funnel or step users

Export analyzed funnel or users reaching a step.

GET /api/v1/analytics/funnels/:siteId/export?steps=page_view,product_view,purchase&format=csv
GET /api/v1/analytics/funnels/:siteId/steps/:eventName/export?format=json

Funnel definition endpoints

POST   /api/v1/analytics/funnels/definitions
GET    /api/v1/analytics/funnels/definitions/site/:siteId
GET    /api/v1/analytics/funnels/definitions/:id
PUT    /api/v1/analytics/funnels/definitions/:id
DELETE /api/v1/analytics/funnels/definitions/:id
POST   /api/v1/analytics/funnels/definitions/:id/duplicate
GET    /api/v1/analytics/funnels/definitions/site/:siteId/templates
GET    /api/v1/analytics/funnels/definitions/:id/analyze?mode=hybrid
GET    /api/v1/analytics/funnels/:siteId/export
GET    /api/v1/analytics/funnels/:siteId/steps/:eventName/export

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`siteId`	Required	`uuid`	Definition list/create and exports	Site scope for funnel assets and analysis.
`name`	Required	`string`	Create/update definition	Human-readable funnel definition name.
`steps[]`	Required	`array of step definitions`	Create/update definition and export	Ordered funnel steps; export endpoint expects comma-separated step names in query.
`format`	Optional	`csv \| json`	Export endpoints	Export output type.
`startDate / endDate`	Optional	`ISO date`	Analyze/export	Temporal scope overrides.
`mode`	Optional	`hybrid \| journey`	Analyze saved definition	Flow grouping mode for V2 funnel analysis. Default: hybrid.

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Need reusable funnel config	POST /analytics/funnels/definitions	Persists funnel definition for repeated use.
Need inventory of existing funnels	GET /analytics/funnels/definitions/site/:siteId	List and govern saved funnels.
Need one-off analysis from saved funnel	GET /analytics/funnels/definitions/:id/analyze?mode=hybrid	Runs strict V2 funnel analysis without rebuilding step set.
Need exportable dataset for BI	GET /analytics/funnels/:siteId/export	CSV/JSON export for downstream processing.
Need users who reached specific step	GET /analytics/funnels/:siteId/steps/:eventName/export	Step-level user extraction.

Common Errors and Fixes

Analyze endpoint returns validation error

Cause: Saved steps are duplicated, non-canonical, or outside 2-8 step limits.

Fix: Use 2-8 unique canonical event names in saved definition steps.

Export fails with step validation error

Cause: steps query parameter missing or empty.

Fix: Provide at least one comma-separated step name.

Templates list is empty

Cause: No templates available for site context.

Fix: Create a baseline definition or verify template provisioning path.

Duplicate creates confusing naming

Cause: newName not provided in duplicate payload.

Fix: Provide explicit newName to keep governance clean.

Production Checklist

Saved funnels are named with purpose and owner context.Required
Step taxonomies are standardized before definition creation.Required
Exports use bounded date windows for operational stability.Required
Duplicate workflow is used instead of editing production-critical definitions directly.Required
Template usage is documented for onboarding analysts.Required