Run report
run_reportPreview an ANALYSIS or dashboard and return its rows or grouped aggregates: counts, sums, averages, grouping, trends, charts, or a multi-column table the user may want to keep as a View. For a plain LIST of records (open tasks, deals in a stage) call search_records with filters instead — lighter, exact-value, and it never refuses a spec. Pass report_id for a saved analysis/dashboard, or definition for an inline ReportSpec (object + columns + filters + group_by + aggregations; omit viz and the best fit is derived) or a composition (kind:"composition" — each panel has EITHER an inline spec OR source_view_id). A living window is an in_period filter from the closed set (today … this_quarter, overdue, upcoming) — never an invented period name; a fixed window uses gte/lt on the date field. Money comes back in minor units with no manual FX applied; never label a raw or mixed-currency aggregate as a converted total. run_report only PREVIEWS — it never saves. To keep one, the user clicks "Save as view" on the card, or you call create_record with object_type:"report" and data:{name,definition}; never tell the user a View is saved until a save has succeeded. Zero rows is an empty result — say so. When the user is REFINING an analysis or dashboard they already saved, pass its id as source_view_id with the refined definition so the save lands OVER the existing item instead of a twin. E.g. touches by type: {object:"touch",group_by:{ref:{kind:"field",field:"type"}},aggregations:[{fn:"count",alias:"n"}]}. For the full authoring guide (viz recipes, filter logic, related_filters, matrices, rates, dashboards, dashboard filters) read capable://guide/reports.
When to use: Counts, sums, grouping, trends, charts or a keepable table over workspace data; a plain list of records (open tasks, deals in a stage) is search_records. It previews only — nothing is saved until the user saves it or you create_record(report).
Example: Report total ARR by industry for current customers.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| report_id | No | A saved analysis or dashboard's id (uuid), run with its stored definition; give this or definition — report_id wins when both are passed. | |
| definition | No | An inline ReportSpec (object, columns, filters, group_by, aggregations, viz) or a composition (dashboard) to preview; omit when passing report_id. | |
| source_view_id | No | Id (uuid) of the saved View this inline definition refines, so a save updates it in place instead of creating a twin; ignored with report_id. | |
| suggested_name | No | A name to seed the card's "Save as view" button, echoed as suggested_name; only meaningful with an inline definition (this call saves nothing). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| viz | No | ||
| kind | No | ||
| mode | No | ||
| note | No | ||
| rows | No | ||
| spec | No | ||
| empty | No | ||
| title | No | ||
| deltas | No | ||
| layout | No | ||
| object | No | ||
| period | No | ||
| columns | No | ||
| widgets | No | ||
| group_ref | No | ||
| row_count | No | ||
| truncated | No | ||
| board_group | No | ||
| aggregations | No | ||
| group_bucket | No | ||
| source_view_id | No | ||
| suggested_name | No | ||
| group_ref_secondary | No |