Analytics and ads — Voidhash Docs

These commands read events and business metrics, run the charts Studio shows, manage alerts, and connect and report on Meta ad accounts.

Events

Command	What it does	Key flags
`events list`	The latest events, newest first.	`--name`, `--person`, `--limit` (default 25)
`events tail`	Shows events as they arrive, until Ctrl+C.	`--name`, `--person`, `--interval` (default 2 seconds), `--count`
`events policy view`	Which built-in events are stored and which custom events are blocked.
`events policy enable [event]`	Starts storing a built-in event, such as `$pageview`.
`events policy disable [event]`	Stops storing a built-in event. Asks first.
`events policy block [event]`	Stops storing a custom event. Asks first.
`events policy unblock [event]`	Stores a blocked custom event again.

See Events for built-in and custom events.

Reports take a period of complete days: --last 30d (also 7d, 4w, 3m, 1y) ends yesterday, and --from 2026-09-01 --to 2026-09-30 names the days. Where a report takes --environment, it reads production purchases by default, or sandbox or test ones; see environments.

Command	What it does	Key flags
`insights list`	The built-in metrics `insights run` takes.
`insights run [insight…]`	Runs metrics such as `mrr` or `"trial conversion rate"` over a period.	`--last`, `--by hour\|day\|week\|month\|quarter\|year`, `--product`, `--environment` (also `all`), `--compare`
`analytics charts`	The charts Studio shows, by what they answer.	`--section`
`analytics chart <chart>`	Runs one chart, such as retention or paywall conversion.	`--last`, `--by`, `--dimension`, `--metric`, `--timezone`
`analytics acquisition`	Who each network, campaign, ad set, ad or surface brought in, and what they paid.	`--by network\|campaign\|adset\|ad\|surface`, `--network`, `--campaign`, `--attribution-window-days`, `--key-conversion signup\|trial\|payer`, `--currency`, `--environment`
`analytics cohorts`	Revenue of weekly acquisition cohorts by day 0, 7, 30, 90, 180 and 365.	`--by surface\|network\|campaign\|adset`, `--currency`, `--environment`
`analytics health`	Web page views by host, app SDKs and versions, and web-to-app handoffs.

analytics charts --section takes overview, revenue, subscribers, trials, churn, audience, paywalls, acquisition, web, app, locations, push or health.

analytics acquisition, analytics cohorts and analytics chart cut days in UTC unless --timezone says otherwise. The first two report money in USD unless --currency says otherwise.

Alerts

Command	What it does	Key flags
`analytics alerts list`	Alerts and how each stood at its latest hourly check.
`analytics alerts create`	Adds an alert.	`--name`, `--kind event_count\|failure_share\|volume_drop`, `--event`, `--success-event`, `--window-hours 1\|6\|24\|168`, `--threshold`, `--min-people` (default 2)
`analytics alerts enable <alert>`	Turns an alert back on.
`analytics alerts disable <alert>`	Turns an alert off without deleting it.
`analytics alerts delete <alert>`	Deletes an alert. Asks first.

--threshold is a count of at least 1 for event_count, and a share between 0 and 1 for failure_share and volume_drop, such as 0.2 for 20%; Studio asks for a percentage. --success-event is for failure_share only, and --min-people for event_count only; use 1 when one person matters. enable, disable and delete take an alert's ID or exact name. To change what an alert watches, use Studio, the API or the update_analytics_alert MCP tool. Reading alerts needs project:analytics:read; changing them needs project:analytics:write.

voidhash analytics alerts create --name "Purchases failing" --kind failure_share \
  --event purchase_failed --success-event purchase_succeeded --window-hours 24 --threshold 0.2

Command	What it does	Key flags
`ads accounts`	Connected ad accounts and their sync health.
`ads connect [account]`	Connects a Meta ad account with a system user token, asked for hidden or piped in.	`--token-stdin`, `--backfill-days` (default 90, at most 1,095)
`ads disconnect [account]`	Disconnects an account and deletes what was synced from it. Asks first.
`ads campaigns [campaign]`	Synced campaigns, or one campaign's ad groups and ads.	`--account`, `--status`, `--delivery`, `--destination`, `--search`
`ads report performance`	What each campaign, ad group or ad spent and earned.	`--level campaign\|ad-group\|ad`, `--breakdown`, `--sort`, `--limit` (default 50)
`ads report creatives`	Creatives by spend, with fatigue signs.	`--format image\|video\|carousel`, `--search`, `--limit` (default 25)
`ads report cohorts`	Payback by acquisition cohort.	`--by platform\|surface\|campaign\|ad-group`, `--unit week\|month`, `--metric roas\|revenue-per-payer\|payers`
`ads issues`	Failing syncs, rejected or held ads, and ads missing tracking parameters.
`ads settings view`	The landing pages that mark website ads as web-to-app.
`ads settings web-to-app [prefix…]`	Sets exactly those landing page prefixes.	`--clear`
`ads measurement view`	Whether purchases reach Meta's Conversions API, and the install referrer key's state.
`ads measurement edit`	Sets up the Conversions API and install referrer key. Enabling asks first.	`--enable`, `--disable`, `--dataset`, `--token`, `--token-stdin`, `--test-event-code`, `--install-referrer-key`

Ads reports default to your ad accounts' time zone and currency. Tokens and keys are never passed as a flag's value. See Ad attribution in your app and Ad measurement.

Example

voidhash insights run mrr churn-rate --last 90d --by week --compare
voidhash events tail --name '$paywall_viewed'

Next steps

Metric definitions: how each metric is computed.
Alerts: alert kinds and thresholds.
Ad measurement: connect Meta and read ad reports.