---
title: Insights and dashboards
description: 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.
section: cloud
order: 253
audience: [builder, agent, user]
sources: [services/nodejs-cloud/lib/analytics/query.ts, services/nodejs-cloud/lib/analytics/insights.ts, services/nodejs-cloud/components/exp/InsightsPage.tsx, services/nodejs-cloud/components/globe/editor/insight.tsx, docs/adr/0054-venom-experiments.md]
features: [cloud.experiments, cloud.page-exp]
---

Insights answer product questions from the events your apps already send with `track()` ([sending
events](/docs/cloud/experiments-events.md)): 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:

````text
```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](/docs/developers/experiments.md#tools)).
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](/docs/developers/experiments.md#rest)). Reading needs `flags:read`,
saving `flags:write`.

A query is a small object:

```json
{ "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.
