Insights and dashboards
Understand saved analytics, windows, retention, and dashboard tiles.
An insight saves a question’s definition, not its result. Every run recomputes it for the resolved period. A dashboard arranges saved insights and text into tiles. Both belong to the active product.
Read Analytics for catalog discovery and one-off questions.
Insight definitions
Field | Accepted values or limits |
|---|---|
slug | 2–64 lowercase letters, digits, or hyphens; starts with a letter or digit. Unique in the product and immutable. |
name, description | Name up to 120 characters; optional description up to 2,000. |
kind | trend, funnel, number, or retention. |
series | 1–8 requests, each keyed by one capital letter such as A. |
formula | Optional arithmetic using defined series keys, up to 500 characters. Not allowed for retention insights. |
window | Absolute timestamp bounds or a relative period. |
grain | day, week, or month; defaults to day. |
display | line, bar, bold_number, or table; defaults to line. |
tags | Up to 20, each up to 40 characters. |
target | Optional >=, <=, or = comparison with a number. |
A series holds a metric query, funnel, or retention request, validated before saving. Each produces one number per bucket: a metric series cannot contain multiple metrics or group by a dimension. Use separate series for separate metrics or groups.
Formulas and missing values
For a fictional Acme report, let A count all qualifying events and B count those from a selected source. round(B / A * 100, 1) expresses that source’s percentage. Discover the actual entity and metric names in Acme’s catalog before building either series.
Formulas accept +, -, *, /, unary minus, parentheses, numeric literals, round(value, places), and coalesce(value, fallback). Rounding places must be a literal integer up to 15. Unknown series keys and syntax errors are rejected when saving.
A missing operand makes the result null unless you explicitly use coalesce. Division by zero and overflow also return null. Do not read a null bucket as zero.
Windows
Relative windows are last_7d, last_30d, last_90d, or cycle. The day ranges include today: last_7d means today and the preceding six days. Absolute windows use from and to. Buckets use whole UTC days at their finest grain.
cycle resolves to the platform’s current configured cycle on each run. If none is configured, the run fails; check the catalog or override both bounds for the run. A saved cycle is not a permanent copy of a closed period.
A saved run may override from, to, or both, without changing the stored definition. It cannot replace the series, formula, or target. A definition can also be previewed without saving through POST /analytics/insights/run.
Results
A run returns the definition, resolved window, aligned series with null gaps, evaluated formula, totals, and target_status (met, missed, or null). Inline runs have no stored definition. Retention results also carry cohort size and retained counts so a rate can be interpreted with its denominator.
Retention
Retention counts subjects whose first matching cohort event falls in a bucket, then checks for a return event starting on day N.
Input | Meaning |
|---|---|
entity | A catalog entity. |
subject | identity or a raw event property such as props.customer_id; not a declared dimension. |
cohort, return | Filters for the starting and returning events. Empty filters mean any row. |
day | N, from 1 to 365. |
return_window_days | Return window beginning on day N: 1–90 days, default 7. |
from, to, grain | Inclusive UTC cohort range and bucket size. |
Each subject is counted once. Identity uses the first non-null identity; a property subject is read as text. A cohort whose horizon has not elapsed has null retained counts and rates: not yet measurable. Totals include only measurable buckets, and meta.unmeasurable_buckets counts the omitted buckets. Retention reads live data rather than pre-aggregated results.
Event properties
Where the catalog exposes a properties column, props.<key> can group or filter on a raw property. Keys are single-level: a dot inside the key is literal, not a nested path. Quotes and backslashes are not accepted in keys.
Property values compare as strings, including numeric and boolean filter values. Unknown dimensions or a property request on an entity without properties are rejected. Grouping or filtering by a property reads the whole range live, because pre-aggregated data does not carry those properties.
Dashboard tiles
A dashboard has an immutable slug under the same rules as insights, a name up to 120 characters, up to 20 tags, and up to 40 tiles. Each tile has layout coordinates x, y, w, and h on a 12-column grid. Rows can extend downward; each tile’s width and height are 1–12 cells. Tile IDs must be unique; supplied IDs are preserved, otherwise generated.
An insight tile refers to a saved insight ID. A text tile holds Markdown up to 4,000 characters. A tile can also have a title.
Running a dashboard returns the board and every tile. Each tile result is the insight result, an error with status and message, or null for text. A failing tile does not fail the entire dashboard response.
Deleting an insight still referenced by a dashboard returns 409 and names the boards. Remove the references before deleting the insight.
Operations and app behavior
Task | MCP tool |
|---|---|
Create, list, read insights | analytics_insight_create, analytics_insight_list, analytics_insight_get |
Update, delete, run insights | analytics_insight_update, analytics_insight_delete, analytics_insight_run |
Create, list, read dashboards | analytics_dashboard_create, analytics_dashboard_list, analytics_dashboard_get |
Update, delete, run dashboards | analytics_dashboard_update, analytics_dashboard_delete, analytics_dashboard_run |
These are product-scoped operations. Read requires the corresponding read permission; creating and editing require write permission. The Analytics API reference carries HTTP equivalents.
Reading accepts an ID or slug; updates and deletion require the ID. Lists return definitions newest first, filtered by exact tag and case-insensitive q over name or slug, combined with AND. Updates change supplied fields only; unknown fields and empty changes are rejected.
In Analytics → Insights, compose series, formula, window, grain, display, tags, and target. Retention definitions can be created through MCP or REST but are read-only in the app. Dashboards arranges insight and text tiles; opening a board runs it. Save name and tag edits by submitting them.