Funnels

Funnels track user progression through a sequence of steps, like an onboarding flow or checkout process. Definitions are scoped to projects. Each step has a name and an event filter that matches on step_name and/or screen_name.

List funnels

owlmetry funnels list --project-id <id>

Lists all funnel definitions for a project.

Flag	Required	Description
`--project-id <id>`	Yes	Project UUID

View a funnel

owlmetry funnels view <slug> --project-id <id>

Shows the funnel definition including its steps, event filters, and description.

Argument / Flag	Required	Description
`<slug>`	Yes	Funnel slug
`--project-id <id>`	Yes	Project UUID

Create a funnel

owlmetry funnels create --project-id <id> --name <name> --slug <slug> --steps <json> [--steps-file <path>] [--description <desc>]

Flag	Required	Description
`--project-id <id>`	Yes	Project UUID
`--name <name>`	Yes	Display name
`--slug <slug>`	Yes	Unique identifier (lowercase letters, numbers, hyphens only)
`--steps <json>`	Yes*	Steps as a JSON array (see format below)
`--steps-file <path>`	Yes*	Path to a JSON file containing steps (alternative to `--steps`)
`--description <desc>`	No	Short description

*One of --steps or --steps-file is required. They are mutually exclusive.

Step format

Each step is a JSON object with name and event_filter. The event_filter matches events by step_name and/or screen_name. The step_name value should match the string you pass to track() in the SDK.

[
  { "name": "sign-up", "event_filter": { "step_name": "sign-up" } },
  { "name": "onboarding", "event_filter": { "step_name": "onboarding" } },
  { "name": "first-purchase", "event_filter": { "step_name": "first-purchase" } }
]

Maximum 20 steps per funnel.

Example

owlmetry funnels create \
  --project-id 550e8400-... \
  --name "Onboarding" \
  --slug onboarding \
  --description "New user onboarding flow" \
  --steps '[{"name":"sign-up","event_filter":{"step_name":"sign-up"}},{"name":"profile-setup","event_filter":{"step_name":"profile-setup"}},{"name":"first-action","event_filter":{"step_name":"first-action"}}]'

Query funnel analytics

owlmetry funnels query <slug> --project-id <id> [options]

Returns step-by-step analytics: unique users at each step, percentage of start, and drop-off rates.

Argument / Flag	Required	Description
`<slug>`	Yes	Funnel slug
`--project-id <id>`	Yes	Project UUID
`--since <time>`	No	Start time. Relative (`1h`, `30m`, `7d`) or ISO 8601.
`--until <time>`	No	End time. Relative (`1h`, `30m`, `7d`) or ISO 8601.
`--open`	No	Use open (independent) mode instead of closed (sequential) mode
`--app-version <version>`	No	Filter by app version
`--environment <env>`	No	Filter by environment: `ios`, `ipados`, `macos`, `android`, `web`, `backend`
`--experiment <name:variant>`	No	Filter by experiment assignment (format: `name:variant`)
`--group-by <field>`	No	Segment results (see below)
`--data-mode <mode>`	No	`production` (default), `development`, or `all`

Funnel modes

Closed (default) — sequential. Users must complete each step in order. A user who skips step 2 is not counted at step 3.
Open (--open) — independent. Each step is evaluated separately. Users can appear at any step regardless of earlier steps.

Group-by options

Value	Description
`environment`	Segment by environment
`app_version`	Segment by app version
`experiment:<name>`	Segment by experiment variant assignment

Examples

# Closed funnel for the last 30 days
owlmetry funnels query onboarding --project-id 550e8400-... --since 2025-01-01

# Open funnel
owlmetry funnels query onboarding --project-id 550e8400-... --open

# A/B test comparison
owlmetry funnels query onboarding --project-id 550e8400-... --group-by experiment:onboarding-variant

# Filter to a specific experiment arm
owlmetry funnels query onboarding --project-id 550e8400-... --experiment onboarding-variant:control

Update a funnel

owlmetry funnels update <slug> --project-id <id> [options]

Argument / Flag	Required	Description
`<slug>`	Yes	Funnel slug
`--project-id <id>`	Yes	Project UUID
`--name <name>`	No	New display name
`--description <desc>`	No	New description
`--steps <json>`	No	New steps as JSON array
`--steps-file <path>`	No	Path to a JSON file containing new steps (alternative to `--steps`)

# Rename a funnel
owlmetry funnels update onboarding --project-id 550e8400-... --name "New User Onboarding"

# Replace steps
owlmetry funnels update onboarding --project-id 550e8400-... \
  --steps '[{"name":"sign-up","event_filter":{"step_name":"sign-up"}},{"name":"tutorial","event_filter":{"step_name":"tutorial"}}]'

Delete a funnel

owlmetry funnels delete <slug> --project-id <id>

Soft-deletes the funnel definition. Existing funnel events are not removed.

Argument / Flag	Required	Description
`<slug>`	Yes	Funnel slug
`--project-id <id>`	Yes	Project UUID

Ready to get started?

Install the CLI and let your agent handle the rest.

Get Started GitHub

On this page