Create and query a Calculated Insight in Salesforce Data Cloud to surface pre-aggregated metrics and dimensions
domain: developer.salesforce.com · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
In-depth guide
Salesforce Bulk API 2.0 limits — the full failure-mode walkthrough related to developer.salesforce.com, checked against official docs, with linked verified routes.
Steps
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 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?