Analytics
Ask about product data or query declared metrics directly.
Analytics answers questions about data available for your active product. Ask in plain English for exploration, use declared metrics for repeatable queries, or save an insight to run the same definition again.
Only data exposed to analytics can be queried. A product with no available data returns an empty result, not an error.
Ask a question
With MCP, analytics_query_run takes q, such as “How many deployments happened yesterday?” It is a product-scope read operation and needs an authenticated identity, a product_id, and permission for that operation.
The REST equivalent is POST /analytics/query, with the same q input. Product context comes from the authenticated request, not a product-selection argument in the question.
The service reads the product’s available entities and measures, translates the question into a query, applies the product boundary before execution, and phrases the result in words. Counts, sums, averages, ratios, and grouping or filtering are possible where the data exposes them.
Read the response
Field | Meaning |
|---|---|
answer | Plain-English answer. |
sql | Executed query. |
rows | Returned rows. |
truncated | Whether more rows exist beyond the returned result. |
explanation | How the question was interpreted. |
Check the explanation and rows before relying on a number. A truncated response is not a complete listing.
A rejected generated query returns 422; rephrase the question. An upstream failure returns 502. Failure messages are generic and do not include underlying query or storage details.
Query without natural-language translation
Read analytics_catalog_get first. It supplies the actual entities, metrics, dimensions, identity kinds, event-property availability, and configured cycle for this product. Do not assume example metric names exist in every product.
Tool | Question it answers |
|---|---|
Declared metrics by day, week, or month, optionally grouped by a dimension. | |
Conversion through two to five ordered steps. | |
How a cohort returns after a specified interval. | |
Events for a person identified by one identifier. |
These operations resolve names against the catalog instead of generating them with a language model.
Analytics in the web app
Open Analytics in the sidebar.
Screen | Behavior |
|---|---|
Overview | Metric cards for the selected period. Counts and sums total the window; averages and ratios show the last closed bucket and identify it. |
Insights | Search and filter saved definitions; cards run their current values. A failed run leaves no number rather than displaying zero. |
Funnels | Compose two to five steps and run explicitly. Editing a step does not rerun automatically. |
People | Look up one person’s timeline by an identifier; this is not a directory of everybody. |
Dashboards | Open saved tile layouts and run their insights. Submit name or tag edits to save them. |
Retention insights are read-only in the app. Create them through MCP or the API. See Insights and dashboards for saved definitions, windows, and how to interpret missing results.