Reports
A report is a read-only page of blocks (headings, text, numbers, charts and tables) that is computed from the tables of a project. Reports are defined as JSON, which makes them easy to write for agents and easy to review for humans.
Create a report
- Open the project’s Reports tab and click New report.
- Give it a title. An editor opens with a JSON definition on one side and a live preview on the other.
- Edit the definition; the preview updates when the definition is valid. Invalid definitions show an error and are not saved.
Or ask an agent: “Create a report with total revenue, revenue per month and the 10 largest open deals.”
Definition structure
{
"version": 1,
"theme": "light",
"blocks": [
{ "type": "heading", "text": "Revenue", "level": 1 },
{ "type": "markdown", "content": "Numbers are **live** from the Deals table." },
{
"type": "metric", "title": "Won revenue", "width": "third",
"format": "currency", "currency": "EUR",
"query": {
"table_id": 42,
"filters": [{ "field": "Stage", "op": "equal", "value": "Won" }],
"aggregations": [{ "function": "sum", "field": "Amount" }]
}
},
{
"type": "chart", "title": "Revenue per month", "chart_type": "line",
"width": "full",
"query": {
"table_id": 42,
"group_by": [{ "field": "Closed on", "granularity": "month" }],
"aggregations": [{ "function": "sum", "field": "Amount", "alias": "revenue" }],
"order_by": [{ "field": "Closed on" }]
}
},
{ "type": "divider" },
{
"type": "table", "title": "Largest open deals",
"columns": ["Name", "Company", "Amount"],
"query": {
"table_id": 42,
"filters": [{ "field": "Stage", "op": "not_equal", "value": "Won" }],
"order_by": [{ "field": "Amount", "direction": "desc" }],
"limit": 10
}
}
]
}
Blocks
| Block | Required | Options |
|---|---|---|
heading |
text |
level 1–3 |
markdown |
– | content (Markdown, HTML is not rendered) |
divider |
– | – |
metric |
title, query with aggregations and no group_by |
value (which aggregation to show), format number/currency/percent, currency, decimals, prefix, suffix |
chart |
title, query with group_by |
chart_type bar/line/area/pie, x, series |
table |
query |
title, columns |
Every block accepts width: full, half or third. Blocks next to each
other fill a row.
Queries
The query of a block uses the same JSON query language as the
records_query MCP tool:
| Key | Meaning |
|---|---|
table_id |
Table to read; must belong to a database attached to the project. |
select |
Fields to return (table blocks). |
filters |
List of {field, op, value}. Operators: equal, not_equal, contains, not_contains, empty, not_empty, gt, gte, lt, lte, in, or any view filter type such as date_is_within. |
filter_type |
AND (default) or OR. |
search |
Full text search. |
group_by |
List of {field, granularity?, alias?}; granularity day, week, month, quarter or year for dates. |
aggregations |
List of {function, field?, alias?} with count, count_distinct, sum, avg, min, max. The result key is the alias, or function_field. |
order_by |
List of {field, direction}. |
limit, offset |
Paging, up to 1000 rows. |
If one block’s query fails (for example a renamed field), only that block shows an error; the rest of the report still renders.
Live data or snapshots
- A live report runs its queries when it is viewed (cached for 60 seconds when published).
- A snapshot freezes the current result. Click Take snapshot (or use
snapshot_report) to store it; published snapshot reports always show the frozen data. Use snapshots for monthly reports that must not change later.
Next
Share a report outside your workspace: Publishing reports.