> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formo.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics

> Run Formo's pre-built analytics pipes (KPIs, funnels, retention, revenue, and top-N breakdowns) directly from the terminal, without writing SQL.

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>`.

<Note>
  Requires `query:read` scope on your API key.
</Note>

## `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 |

<Note>
  `--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`).
</Note>

### `--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.

```bash theme={null}
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:

```bash theme={null}
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"`.

<Warning>
  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`.
</Warning>

### `--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.

```bash theme={null}
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:

```bash theme={null}
formo analytics retention --params '{"retention_type":"recurring"}'
```

### Examples

```bash theme={null}
# 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 }`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.