|
| 1 | +--- |
| 2 | +title: "Analytics" |
| 3 | +sidebarTitle: "Analytics" |
| 4 | +icon: chart-mixed |
| 5 | +description: "Run Formo's pre-built analytics pipes — KPIs, funnels, retention, revenue, and top-N breakdowns — directly from the terminal, without writing SQL." |
| 6 | +--- |
| 7 | + |
| 8 | +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>`. |
| 9 | + |
| 10 | +<Note> |
| 11 | +Requires `query:read` scope on your API key. |
| 12 | +</Note> |
| 13 | + |
| 14 | +## `formo analytics <pipe>` |
| 15 | + |
| 16 | +### Pipes |
| 17 | + |
| 18 | +| Pipe | Description | |
| 19 | +|------|-------------| |
| 20 | +| `kpis` | Traffic KPIs: visitors, pageviews, bounce rate, session duration | |
| 21 | +| `event_timeseries` | Event counts over time | |
| 22 | +| `funnel` | Conversion funnel across ordered steps | |
| 23 | +| `flow` | User path / flow analysis between steps | |
| 24 | +| `frequency` | Engagement frequency distribution | |
| 25 | +| `lifecycle` | User lifecycle stages (new, returning, power, resurrected, churned) | |
| 26 | +| `retention` | Retention cohort analysis | |
| 27 | +| `revenue_overview` | Revenue overview with optional breakdown | |
| 28 | +| `revenue_by_metric` | Revenue ranked by a metric column | |
| 29 | +| `revenue_timeseries` | Revenue over time (requires `address`) | |
| 30 | +| `volume_by_metric` | Trading volume ranked by a metric column | |
| 31 | +| `top_chains` | Top chains by activity | |
| 32 | +| `top_events` | Top events by count | |
| 33 | +| `top_locations` | Top locations | |
| 34 | +| `top_pages` | Top pages by traffic | |
| 35 | +| `top_sources` | Top acquisition sources | |
| 36 | +| `top_wallets` | Top wallets by activity | |
| 37 | + |
| 38 | +### Options |
| 39 | + |
| 40 | +| Option | Type | Required | Description | |
| 41 | +|--------|------|----------|-------------| |
| 42 | +| `--date-from` | `string` | ❌ | Inclusive start date `YYYY-MM-DD` (default: 7 days before `--date-to`) | |
| 43 | +| `--date-to` | `string` | ❌ | Inclusive end date `YYYY-MM-DD` (default: today) | |
| 44 | +| `--filters` | `string` | ❌ | JSON array of filter conditions: `[{"field": "...", "op": "...", "value": "..."}]` | |
| 45 | +| `--params` | `string` | ❌ | JSON object of pipe-specific params merged into the query | |
| 46 | + |
| 47 | +<Note> |
| 48 | +`--params` may **not** set `date_from`/`date_to`/`filters` — use the dedicated |
| 49 | +`--date-from`/`--date-to`/`--filters` flags for those. Object/array values in |
| 50 | +`--params` are JSON-encoded automatically (e.g. `funnel`'s `steps`). |
| 51 | +</Note> |
| 52 | + |
| 53 | +### `--filters` |
| 54 | + |
| 55 | +A JSON array of `{ field, op, value }` conditions, e.g. `[{"field":"location","op":"equals","value":"US"}]`. For multi-value matching, use `in` / `notIn` with a pipe-delimited `value` (e.g. `"chrome|firefox"`). |
| 56 | + |
| 57 | +### `--params` (pipe-specific) |
| 58 | + |
| 59 | +Some pipes take additional, pipe-specific parameters. Pass them as a JSON object via `--params`: |
| 60 | + |
| 61 | +| Pipe | Key params | |
| 62 | +|------|------------| |
| 63 | +| `kpis`, `revenue_overview` | `group_by`, `limit`, `include_previous_period` | |
| 64 | +| `funnel` | `steps` (required — JSON array of `{type,event,name,filters?}`), `window_seconds`, `funnel_type`, `breakdown` | |
| 65 | +| `flow` | `start_step` (required — JSON `{type,event,resolved_event,...}`), `end_step`, `global_filters`, `window_seconds`, `max_steps` | |
| 66 | +| `retention` | `id_type`, `event_type`, `event_name`, `min_users` | |
| 67 | +| `revenue_timeseries` | `address` (required) | |
| 68 | +| `revenue_by_metric`, `volume_by_metric`, `top_sources` | `metric_column`, `limit`, `offset` | |
| 69 | +| `top_chains`, `top_events`, `top_locations`, `top_pages`, `top_wallets` | `limit`, `offset` | |
| 70 | + |
| 71 | +### Examples |
| 72 | + |
| 73 | +```bash |
| 74 | +# Traffic KPIs for the last 7 days (default range) |
| 75 | +formo analytics kpis |
| 76 | + |
| 77 | +# KPIs for April 2026, broken down by device |
| 78 | +formo analytics kpis --date-from 2026-04-01 --date-to 2026-04-30 --params '{"group_by":"device"}' |
| 79 | + |
| 80 | +# Conversion funnel across ordered steps |
| 81 | +formo analytics funnel \ |
| 82 | + --date-from 2026-04-01 --date-to 2026-04-30 \ |
| 83 | + --params '{"steps":[{"type":"event","event":"page","name":"page::0","filters":[]},{"type":"track","event":"connect","name":"connect::1","filters":[]}],"window_seconds":86400}' |
| 84 | + |
| 85 | +# Top 10 wallets by activity last month |
| 86 | +formo analytics top_wallets --date-from 2026-04-01 --date-to 2026-04-30 --params '{"limit":10}' |
| 87 | + |
| 88 | +# Retention restricted to US visitors |
| 89 | +formo analytics retention --filters '[{"field":"location","op":"equals","value":"US"}]' |
| 90 | + |
| 91 | +# Revenue timeseries for a specific wallet |
| 92 | +formo analytics revenue_timeseries \ |
| 93 | + --date-from 2026-04-01 --date-to 2026-04-30 \ |
| 94 | + --params '{"address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"}' |
| 95 | + |
| 96 | +# Pipe results to jq for processing |
| 97 | +formo analytics kpis | jq '.data' |
| 98 | +``` |
| 99 | + |
| 100 | +The response shape matches the dashboard data: `{ meta, data, rows, statistics }`. |
0 commit comments