Funnels

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:

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:

{
  "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:

{
  "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.

{
  "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:

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:

{
  "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:

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 — apply conditions, breakdowns, and comparisons to any metric
Events — explore the events that power your funnel steps
Boards — save funnel results to a board for ongoing monitoring
Data queries API — full API reference for funnels and other metrics

Getting Started

Tracking

Pipeline

Analytics

Installing

Analyze a funnel

Steps and filters

Step filter operators

Conversion window

Breakdowns

Funnel trends

What’s next

​Analyze a funnel

​Steps and filters

​Step filter operators

​Conversion window

​Breakdowns

​Funnel trends

​What’s next

Analyze a funnel

Steps and filters

Step filter operators

Conversion window

Breakdowns

Funnel trends

What’s next