Skip to main content
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

OperatorAliasesDescription
eq=, ==Equal
ne!=, <>Not equal
gt>Greater than
gte>=Greater than or equal
lt<Less than
lte<=Less than or equal
containslikeContains substring
not_containsnot_likeDoes not contain
starts_withStarts with
ends_withEnds with
inValue is in list
not_inValue is not in list
is_setissetField is not null
is_not_setisnotsetField 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. 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