funnels.create
Define an ordered sequence of steps (events or pageviews with property filters) and evaluate a conversion funnel. Get step-by-step counts, per-step conversion rates, and overall conversion from first to last step.
Instructions
Create and immediately evaluate a conversion funnel. A funnel measures how many unique visitors complete an ordered sequence of steps. Returns step-by-step counts, per-step conversion rates (vs the previous step), and overall conversion (last step / first step). The funnel is saved by name and can be re-evaluated later or for different periods via funnels.list.
Step format: a custom event name like "signup", a pathname-scoped pageview like "pageview:/pricing", and optionally one or more property predicates appended in brackets — "cta_click[location=hero_primary]" matches only cta_click events whose location property equals "hero_primary". Stack predicates to AND them: "cta_click[location=hero_primary][plan=pro]". Predicates work on pageview steps too: "pageview:/pricing[utm_source=google]". Requires Pro plan.
Predicates default to string-typed comparisons (the property is read from the string column). For number- or boolean-typed properties (declared as such in event-schema.yaml), append a type tag: "purchase[count:n=5]" matches numeric 5; "checkout[refunded:b=false]" matches boolean false; "purchase[plan:s=5]" forces string matching when the value looks numeric. Tags: ":n" number, ":b" boolean (true|false|1|0), ":s" string (default).
Examples:
pricing-to-signup → name="pricing-to-signup", steps=["pageview:/pricing", "signup"]
which CTA actually converts → name="hero-cta-funnel", steps=["cta_click[location=hero_primary]", "signup_completed"]
onboarding flow → name="onboarding", steps=["signup", "onboarding_started", "onboarding_completed", "first_purchase"]
multi-item checkouts only → name="multi-item-checkout", steps=["pageview:/cart", "checkout_completed[items:n=3]"]
non-refunded purchases → name="purchase-net", steps=["pageview:/pricing", "purchase[refunded:b=false]"]
blog-to-newsletter → name="blog-newsletter", steps=["pageview:/blog", "newsletter_subscribed"]
Limitations: between 2 and 10 steps; step strings ≤500 chars; names ≤200 chars. Step order matters — once a session skips a step, it cannot complete later steps. Pageview pathnames match exact strings only (no wildcards). Predicate keys must be snake_case; string values may not contain ']' or '['. Number predicates require a finite value; boolean predicates require true|false|1|0. Funnel evaluation is per-session, not per-user across devices. Names must be unique within a project — a duplicate-name create returns 409; use funnels.delete first or pick a new name. Funnel definitions are immutable after creation; to change steps, delete and re-create.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| name | Yes | A descriptive display name for this funnel (e.g. "Pricing → Signup", "Onboarding flow", "pricing-to-signup"). Used to retrieve it later. Permissive charset — spaces, capitals, arrows, and punctuation are all fine. Must not contain "/", ",", "[", or "]" because those collide with URL routing and the step-DSL grammar. Max 200 chars. | |
| steps | Yes | Ordered array of 2-10 funnel steps. Each step: a custom event name ("signup"), a pathname-scoped pageview ("pageview:/pricing"), or either form with property predicates appended in brackets ("cta_click[location=hero_primary]", "pageview:/pricing[utm_source=google]"). Stack predicates to AND them: "cta_click[location=hero_primary][plan=pro]". Predicates default to string matching; append ":n" for number ("checkout[items:n=3]"), ":b" for boolean ("purchase[refunded:b=false]"), or ":s" to force string when the value looks numeric ("plan:s=5"). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| name | Yes | ||
| steps | Yes | ||
| overall_conversion | Yes | ||
| period | Yes |