Funnels

A funnel measures how many users complete an ordered sequence of events — e.g. visited pricing → started signup → verified email → created first project. TrackCrumb computes the funnel at query time over your raw events, so there is no special “funnel event” to emit. You only need to (1) track the step events from your app, then (2) define the funnel in the dashboard.

See the Event Taxonomy for the full list of reserved event names and naming conventions. Pick stable snake_case names — the funnel matches event_name exactly.

Step 1 — Track the step events from your app

Send each step as an ordinary event via tracker.track(). Any custom event name works.

import { TrackCrumb } from "@trackcrumb/sdk-js";
 
const tracker = new TrackCrumb({ apiKey: process.env.TRACKCRUMB_API_KEY });
 
// Funnel: signup → verify → first project
tracker.track("signup_started",        { source: "pricing_page" });
tracker.track("email_verified");
tracker.track("first_project_created", { template: "blank" });

You can also use auto-captured events as funnel steps without writing any code — $pageview, $click, $form_submit. Custom names are usually clearer because they survive UI redesigns.

⚠️

Identify users early. The funnel matches the same distinct_id across steps. If a user starts anonymous and signs in mid-funnel, call tracker.identify(userId) so the events join up. Otherwise the anonymous and signed-in halves count as two different users.

Step 2 — Define the funnel in the dashboard

Go to Funnels in the sidebar (/funnels).

Add your steps in order

Three placeholder steps are seeded by default (page_viewed → button_clicked → form_submitted). Replace each input with the event name you tracked in Step 1. Use + Add step or the × button to grow or trim the list. Minimum two steps.

Set the conversion window

Window (hours) is how long a user has to complete the entire funnel after firing the first step. Default 24, max 720 (30 days). Pick a window that reflects your product’s natural usage rhythm — too short and you’ll undercount; too long and you’ll over-attribute.

Pick a date range

Use the filter bar above the Run funnel button. The date range bounds the first step — later steps must occur within windowHours of the first step, even if they fall outside the date range.

Run it

Click Run funnel. The result renders as a step-by-step block showing the unique-user count at each step and the percentage conversion from the previous step.

Click Save to keep the definition for later — it’ll appear in Saved and can be re-run with one click.

How the conversion is computed

For each step, the funnel counts unique users (DISTINCT distinct_id):

Step 0 = users who fired steps[0] inside the date range.
Step N = users from step N-1 who also fired steps[N] after their first occurrence of steps[N-1], within windowHours.

A user who fires the same step ten times only counts once. The window is anchored to each user’s first occurrence of the previous step, not their most recent.

Calling the API directly

The dashboard hits POST /api/v1/query/funnel. You can call it yourself for embedded reports or scheduled exports:

curl -X POST https://api.trackcrumb.com/api/v1/query/funnel \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"steps":["signup_started","email_verified","first_project_created"],"dateFrom":"2026-04-01","dateTo":"2026-04-29","windowHours":72}'

Response:

{
  "steps": [
    { "name": "signup_started",        "count": 1240, "conversionPct": null },
    { "name": "email_verified",        "count":  860, "conversionPct": 69.4 },
    { "name": "first_project_created", "count":  412, "conversionPct": 47.9 }
  ]
}

Limits & gotchas

Limit	Value
Min steps	2
Max window	720 hours (30 days)
Event-name length	1–255 chars

Property filters aren’t supported on funnels yet. Only /trend accepts a filters array. If you need “signups from Google ads only”, emit a distinct event name (signup_started_google_ads) at tracking time.
Funnels are per-user, not per-session. A user who completes step 1 on Monday and step 2 on Wednesday counts as a conversion as long as it’s within the window.
No automatic anonymous → identified stitching. Call identify() to bind the anonymous browser id to your user id once known.
Same event repeated doesn’t progress the funnel — only the next step in the list does.

Event Taxonomy — naming conventions and reserved events
Trends — single-event time series
Retention — cohort-based long-term return rate
Saved queries — persist a funnel definition

Trends Retention