---
title: Get funnel statistics
description: 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`.

```typescript
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`

`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`:

```typescript
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](/sdk/funnels/getfunnel) to inspect the configured step definitions before interpreting results.