In Data Cloud Setup, navigate to Calculated Insights and click New; write an ANSI SQL SELECT statement that uses aggregate functions (SUM, AVG, COUNT) for measures and non-aggregated columns for dimensions, then save and activate the insight.
Retrieve metadata about available calculated insights via GET https://<tenant-url>/api/v1/insight/metadata/ — the response lists each insight's name, measures, dimensions, and related DMOs.
Query insight data via POST https://<tenant-url>/api/v1/insights/<calculatedInsightApiName> with a JSON body specifying sql (optional filter), limit, offset, and timePeriod granularity (HOUR, DAY, MONTH, QUARTER, YEAR).
Paginate through the response using the limit and offset parameters; each response includes the data rows and a count of total matching records.
Reference the insight from the Data Cloud Query API with standard SQL: SELECT <measureName>, <dimensionName> FROM <InsightApiName>__dlm.
Monitor calculated insight run history in Data Cloud Setup to verify that scheduled refreshes are completing without errors before relying on query results.
Known gotchas
Calculated Insights are pre-aggregated at run time, not at query time — results reflect the state of the last completed insight run, not live DMO data.
The SQL in a Calculated Insight definition cannot contain subqueries or CTEs; flatten all logic into a single SELECT with aggregate functions.
Dimension cardinality affects storage and refresh time — avoid including very high-cardinality columns (e.g., raw event IDs) as dimensions.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp