Projects & memory

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

  1. Open the project’s Reports tab and click New report.
  2. Give it a title. An editor opens with a JSON definition on one side and a live preview on the other.
  3. 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.