Analytics - Formo Docs

The formo analytics command exposes Formo’s pre-built analytics pipes (the same data that powers the Formo dashboard) as terminal commands. Each pipe is a subcommand: formo analytics <pipe>.

Requires query:read scope on your API key.

`formo analytics <pipe>`

Pipes

Pipe	Description
`kpis`	Traffic KPIs: visitors, pageviews, bounce rate, session duration
`event_timeseries`	Event counts over time
`funnel`	Conversion funnel across ordered steps
`flow`	User path / flow analysis between steps
`frequency`	Engagement frequency distribution
`lifecycle`	User lifecycle stages (new, returning, power, at risk, churned, resurrected)
`retention`	Retention cohort analysis
`revenue_overview`	Revenue overview with optional breakdown
`revenue_by_metric`	Revenue ranked by a metric column
`revenue_timeseries`	Revenue over time (requires `address`)
`volume_by_metric`	Trading volume ranked by a metric column
`top_chains`	Top chains by activity
`top_events`	Top events by count
`top_locations`	Top countries
`top_pages`	Top pages by traffic
`top_sources`	Top acquisition sources
`top_wallets`	Top wallets by activity

Options

Option	Type	Required	Description
`--date-from`	`string`	❌	Inclusive start date `YYYY-MM-DD` (default: 7 days before `--date-to`)
`--date-to`	`string`	❌	Inclusive end date `YYYY-MM-DD` (default: today)
`--filters`	`string`	❌	JSON array of filter conditions: `[{"field": "...", "op": "...", "value": "..."}]`
`--params`	`string`	❌	JSON object of pipe-specific params merged into the query

--params may not set date_from/date_to/filters; use the dedicated --date-from/--date-to/--filters flags for those. Object/array values in --params are JSON-encoded automatically (e.g. funnel’s steps).

`--filters`

A JSON array of { field, op, value } filters, e.g. [{"field":"location","op":"eq","value":"US"}]. For multi-value matching, use in / nin with an array value (e.g. ["chrome","firefox"]); pipe-delimited strings remain supported by the analytics query boundary. Use this array for event and user-attribute predicates. On the user-aggregate pipes (lifecycle, frequency) it also takes profile metrics, social identity fields, a lifecycle entry ({"field":"lifecycle","op":"in","value":["New","Power user"]}), and resource entries using the stable fields chains.balance, apps.balance, tokens.balance and labels.value with named qualifiers (chain_id, app_id, token_address, scope, tag_id). Qualifiers must be non-empty strings; the CLI validates required and forbidden qualifiers before sending the request.

formo analytics lifecycle \
  --filters '[{"field":"chains.balance","op":"gt","value":1000,"chain_id":"1"}]'

On lifecycle and frequency, either-touch attribution filters can use a fields pair instead of field. Supply exactly two non-empty column names and only one selector:

formo analytics lifecycle \
  --filters '[{"fields":["first_utm_source","last_utm_source"],"op":"eq","value":"twitter"}]'

Overview Data source filters use field: "channel" with web, mobile, api, import, server, or onchain. Acquisition channel uses channel_type. User-aggregate source filters use source_filter through --params with field: "source".

The retired per-family params — socials, chain_filters, app_filters, token_filters, label_filters, profile_filters, lifecycle_filter — are rejected with a 400 if passed through --params. Forwarding them would silently drop the predicate and broaden the result set, so the API fails loud instead. Send a canonical entry in --filters.

`--params` (pipe-specific)

Some pipes take additional, pipe-specific parameters. Pass them as a JSON object via --params:

Pipe	Key params
`kpis`	`group_by`, `include_previous_period`
`revenue_overview`	`group_by`, `rank_by`, `include_previous_period`
`funnel`	`steps` (required, a JSON array of `{type,event,name,filters?,events?}`), `window_seconds`, `funnel_type`, `group_by`, `limit`, `attribution`
`flow`	`start_step` (required, a JSON `{type,event,resolved_event,...}`), `end_step`, `global_filters`, `window_seconds`, `max_steps`
`retention`	`retention_type` (`rolling` by default or `recurring`), `id_type`, `event_type`, `event_name`, `min_users`
`revenue_timeseries`	`address` (required)
`revenue_by_metric`, `volume_by_metric`, `top_sources`	`metric_column`, `limit`, `offset`
`top_chains`, `top_events`, `top_locations`, `top_pages`, `top_wallets`	`limit`, `offset`
`kpis`, `top_`, `revenue_`, `volume_by_metric`	`page_scope` — `page` (default) or `session`

page_scope only affects requests that carry a page filter. The default scopes metrics to activity on that page; session restores the legacy behaviour where metrics include all activity in any session that viewed the page.

Funnel OR groups

A funnel step can include events to match alternatives with OR logic. The executable group can contain at most 10 events in total, including the primary type/event, which is always included. Step-level filters apply to the whole group; each alternative’s filters apply only to that member. This feature applies to funnel steps, rather than user-path anchors or retention entry filters.

formo analytics funnel \
  --params '{"steps":[{"type":"track","event":"Swap","name":"trade","events":[{"type":"track","event":"Limit Order","filters":[{"field":"amount","op":"gte","value":100}]}]},{"type":"track","event":"Complete","name":"complete"}]}'

Rolling and recurring retention

Rolling retention counts cohort members active in week N or any later week. Recurring retention counts members active in exactly week N. Rolling is the default; select recurring explicitly:

formo analytics retention --params '{"retention_type":"recurring"}'

Examples

# Traffic KPIs for the last 7 days (default range)
formo analytics kpis

# KPIs for April 2026, broken down by device
formo analytics kpis --date-from 2026-04-01 --date-to 2026-04-30 --params '{"group_by":"device"}'

# Conversion funnel across ordered steps
formo analytics funnel \
  --date-from 2026-04-01 --date-to 2026-04-30 \
  --params '{"steps":[{"type":"event","event":"page","name":"page::0","filters":[]},{"type":"track","event":"connect","name":"connect::1","filters":[]}],"window_seconds":86400}'

# Top 10 wallets by activity last month
formo analytics top_wallets --date-from 2026-04-01 --date-to 2026-04-30 --params '{"limit":10}'

# Retention restricted to US visitors
formo analytics retention --filters '[{"field":"location","op":"eq","value":"US"}]'

# Revenue timeseries for a specific wallet
formo analytics revenue_timeseries \
  --date-from 2026-04-01 --date-to 2026-04-30 \
  --params '{"address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"}'

# Pipe results to jq for processing
formo analytics kpis --json | jq '.data'

The response shape matches the dashboard data: { meta, data, rows, statistics }.

​formo analytics <pipe>

​Pipes

​Options

​--filters

​--params (pipe-specific)

​Funnel OR groups

​Rolling and recurring retention

​Examples

`formo analytics <pipe>`

Pipes

Options

`--filters`

`--params` (pipe-specific)

Funnel OR groups

Rolling and recurring retention

Examples