> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tell.rs/llms.txt
> Use this file to discover all available pages before exploring further.

# Funnels

> Measure step-by-step conversion — see where users drop off between key events.

Funnels track how users move through a sequence of events. Define the steps (sign up, add to cart, purchase), set a conversion window, and Tell shows you how many users completed each step, where they dropped off, and overall conversion rate.

## Analyze a funnel

Send a POST request with your steps and a conversion window:

```bash theme={null}
curl -X POST https://your-tell-server/api/v1/funnels \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [
      { "event": "sign_up" },
      { "event": "add_to_cart" },
      { "event": "purchase" }
    ],
    "window_seconds": 604800,
    "range": "30d"
  }'
```

Response:

```json theme={null}
{
  "data": {
    "steps": [
      { "step": 1, "event": "sign_up",    "count": 1200, "overall_rate": 1.0,   "step_rate": 1.0,   "drop_off": 0 },
      { "step": 2, "event": "add_to_cart", "count": 480,  "overall_rate": 0.4,   "step_rate": 0.4,   "drop_off": 720 },
      { "step": 3, "event": "purchase",    "count": 192,  "overall_rate": 0.16,  "step_rate": 0.4,   "drop_off": 288 }
    ],
    "overall_conversion": 0.16
  }
}
```

Each step shows:

* **count** — users who reached this step
* **overall\_rate** — conversion from step 1 (0.0 to 1.0)
* **step\_rate** — conversion from the previous step
* **drop\_off** — users lost between this step and the previous one

## Steps and filters

A funnel needs 2–10 steps. Each step is an event name, optionally with property filters:

```json theme={null}
{
  "steps": [
    { "event": "sign_up" },
    {
      "event": "add_to_cart",
      "filters": [
        { "field": "properties.category", "operator": "eq", "value": "electronics" }
      ]
    },
    { "event": "purchase" }
  ],
  "window_seconds": 604800,
  "range": "30d"
}
```

This funnel only counts `add_to_cart` events where the `category` property equals `"electronics"`. The other steps accept any matching event.

### Step filter operators

| Operator       | Aliases    | Description           |
| -------------- | ---------- | --------------------- |
| `eq`           | `=`, `==`  | Equal                 |
| `ne`           | `!=`, `<>` | Not equal             |
| `gt`           | `>`        | Greater than          |
| `gte`          | `>=`       | Greater than or equal |
| `lt`           | `<`        | Less than             |
| `lte`          | `<=`       | Less than or equal    |
| `contains`     | `like`     | Contains substring    |
| `not_contains` | `not_like` | Does not contain      |
| `starts_with`  |            | Starts with           |
| `ends_with`    |            | Ends with             |
| `in`           |            | Value is in list      |
| `not_in`       |            | Value is not in list  |
| `is_set`       | `isset`    | Field is not null     |
| `is_not_set`   | `isnotset` | Field is null         |
| `regex`        | `~`        | Regex match           |

For custom properties, prefix the field with `properties.` (e.g., `properties.plan`). Top-level fields like `country` or `device_type` use the field name directly.

## Conversion window

The `window_seconds` parameter sets the maximum time a user has to complete the entire funnel from their first step. Default is `604800` (7 days).

A user who triggers step 1 on Monday and step 3 on the following Sunday (within 7 days) counts as converted. A user who takes 8 days does not.

```json theme={null}
{
  "steps": [
    { "event": "trial_start" },
    { "event": "subscription_created" }
  ],
  "window_seconds": 1209600,
  "range": "90d"
}
```

This gives users a 14-day window to convert from trial to subscription.

## Breakdowns

Add a `breakdown` field to split funnel results by a dimension:

```bash theme={null}
curl -X POST https://your-tell-server/api/v1/funnels \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [
      { "event": "sign_up" },
      { "event": "purchase" }
    ],
    "window_seconds": 604800,
    "breakdown": "country",
    "range": "30d"
  }'
```

Response includes a `breakdown` array, each group with its own step results and conversion rate:

```json theme={null}
{
  "data": {
    "steps": [ ... ],
    "overall_conversion": 0.16,
    "breakdown": [
      {
        "dimension": "US",
        "steps": [
          { "step": 1, "event": "sign_up", "count": 600, "overall_rate": 1.0, "step_rate": 1.0, "drop_off": 0 },
          { "step": 2, "event": "purchase", "count": 120, "overall_rate": 0.2, "step_rate": 0.2, "drop_off": 480 }
        ],
        "overall_conversion": 0.2
      },
      {
        "dimension": "DE",
        "steps": [
          { "step": 1, "event": "sign_up", "count": 300, "overall_rate": 1.0, "step_rate": 1.0, "drop_off": 0 },
          { "step": 2, "event": "purchase", "count": 36, "overall_rate": 0.12, "step_rate": 0.12, "drop_off": 264 }
        ],
        "overall_conversion": 0.12
      }
    ]
  }
}
```

Use breakdowns to compare conversion across countries, device types, plans, or any property.

## Funnel trends

Track how conversion changes over time with the trend endpoint:

```bash theme={null}
curl -X POST https://your-tell-server/api/v1/funnels/trend \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [
      { "event": "sign_up" },
      { "event": "purchase" }
    ],
    "window_seconds": 604800,
    "range": "30d",
    "granularity": "daily"
  }'
```

Returns time series data with the overall conversion rate bucketed by the requested granularity. Use this to spot trends — is your onboarding funnel improving week over week?

Supported granularity values: `minute`, `hourly`, `daily`, `weekly`, `monthly`, `quarterly`, `yearly`.

## What's next

* [Filtering](/analytics/filtering) — apply conditions, breakdowns, and comparisons to any metric
* [Events](/analytics/events) — explore the events that power your funnel steps
* [Boards](/analytics/boards) — save funnel results to a board for ongoing monitoring
* [Data queries API](/api/queries) — full API reference for funnels and other metrics