Get funnel statistics

Retrieve dashboard-ready step counts, conversion, drop-off, and timing statistics for a funnel.

Use clics.funnels.getFunnelStats to retrieve the same results shown in the Funnel view in Dashboard. It evaluates the funnel’s configured, ordered steps against traffic in the selected scope.

What you need

Field	Required	Description
`funnelId`	Yes	ID returned by `createFunnel` or `listFunnels`
`dateRange`	No	One of the nine presets; defaults to `last7days`
`start` and `end`	No	Custom `yyyy-MM-dd` or ISO8601 range; always pass both together
`domain`	No	One hostname, or `localhost` for development traffic
`timezone`	No	IANA timezone used for calendar boundaries; defaults to `UTC`
`referrerAiProvider`	No	`chatgpt`, `claude`, `gemini`, `perplexity`, or `copilot`

Presets: last24h, last7days, last30days, last3months, last12months, monthToDate, quarterToDate, yearToDate, and allTime.

const stats = await clics.funnels.getFunnelStats({
  funnelId: "funnel_123",
  dateRange: "last30days",
  timezone: "UTC",
});

console.log(stats.steps[0]?.persons);

What it returns

The response has the saved funnel definition, the calculated values for every step, and the timezone used to evaluate the range.

funnel is the complete saved definition: id, projectId, envId, name, conversionWindow, steps, and createdAt. Each configured step contains its name and its filters (filterType, operator, and values).

`steps`

The steps array is in configured order. Each item is the measured result for that corresponding step:

Field	Type	Description
`stepNumber`	`number`	One-based position in the funnel
`name`	`string`	Step label from the saved definition
`persons`	`number`	Unique visitors who reached this step
`conversionRate`	`number`	Percentage of first-step visitors who reached this step
`conversionFromPreviousRate`	`number`	Percentage of previous-step visitors who reached this step
`droppedOff`	`number`	Visitors who reached this step but not the next one
`droppedOffRate`	`number`	Percentage of this step’s visitors who dropped before the next step
`medianSecondsFromPrevious`	`number`	Median elapsed seconds from the preceding step
`averageSecondsFromPrevious`	`number`	Average elapsed seconds from the preceding step

meta.timezone is the IANA timezone used for calendar period boundaries. Timing fields for the first step are defined by the API and should not be treated as a delay from a prior step.

For a custom range, pass both boundaries. They take precedence over dateRange:

const stats = await clics.funnels.getFunnelStats({
  funnelId: "funnel_123",
  start: "2026-07-01",
  end: "2026-07-31",
  timezone: "Europe/London",
});

Errors and next steps

A missing funnel returns 404.
Passing only one custom date boundary returns 400.
API access requires a paid plan; an unavailable plan returns 403 with UPGRADE_REQUIRED.

Use getFunnel to inspect the configured step definitions before interpreting results.