Insights and dashboards
Trends, funnels and retention over the events your apps send to Venom Experiments, saved as insights and embedded in Notes pages as live dashboards that people and agents can read.
Insights answer product questions from the events your apps already send with track() (sending
events): how many signups a week, where people drop out of checkout, who comes back. Open them
in Venom Experiments → Insights (/exp/insights).
Three kinds
- Trends chart an event over time. Measure the events, the unique units (users, orgs, devices) or the sum of the
events'
value; per hour, day or week; and break down by one event property (the top ten values, the rest as "Other"). Daily and weekly trends without a breakdown read the daily rollups, which are fast for a long range. Hourly trends and breakdowns read the raw events, so an hourly trend looks back at most 7 days. - Funnels take two to eight events in order and a conversion window (1 hour to 30 days). A unit reaches a step when it did that event after the step before, with every step inside the window counted from its first step. Each step shows its units, the share of the step before, the share of the start and how many dropped; the page adds the median time the finishers took, and a table by a property of the first step if you break down. Every first-step event is tried as a start, so an abandoned early visit does not hide a completed later one. A funnel reads raw events for up to 30 days.
- Retention groups units into cohorts by the period of their first event, then shows the share that did the return event (default: the same event) 0, 1, 2 … periods later, by day or week, with a size-weighted average row. A period that has not finished yet is a dash, not a zero, so a young cohort does not look like it left.
Every query is read-only, stops after five seconds (the answer says to use fewer days), and reads a bounded number of rows. When a read hit its cap the chart says so. Nothing leaves your organisation: the queries run on your own events.
Save, embed, share
Save as insight keeps a query with a name. Saved insights are listed on the page; Copy embed puts a block on your clipboard:
```insight
id: 3f1c9a0e-…
```In a Notes page type /insight and pick one, or paste that block. The page then shows the live chart, which refreshes
every time the page is opened and has Refresh, Open and Remove buttons. If Venom Experiments is not on for the
organisation, the insight was deleted, or the reader cannot see Flags data, the block says Insight unavailable
and why. The block is plain markdown (a fenced code block), so a page still reads in other tools, and a published page
shows it as code.
A dashboard is a Notes page with insight blocks. New dashboard on the Insights page makes one from a template (a heading and a block for each insight you pick) in the organisation's vault or your own; it then has everything a Notes page has: sharing, comments, versions and agent access. The Dashboards list shows the pages you can read that embed insights.
From an agent
exp_query_run runs a query and answers as a compact table, exp_insight_save saves one and returns the id to
embed, and exp_insight_list lists the saved ones or runs one by id (see Experiments over MCP).
The same over REST: POST /experiments/api/v1/query, and GET/POST /experiments/api/v1/insights with
/insights/{id} and /insights/{id}/result (the Experiments API). Reading needs flags:read,
saving flags:write.
A query is a small object:
{ "kind": "funnel", "steps": ["view", "add_to_cart", "purchase"], "windowHours": 168, "days": 14, "breakdown": "source" }{ "kind": "trend", "event": "signup", "measure": "units", "interval": "week", "days": 90 } and
{ "kind": "retention", "event": "signup", "returnEvent": "login", "period": "week", "periods": 8 } are the other two.