Use this tool to get statistical summaries of a board's data without fetching individual items. It supports grouping by column values, applying aggregation functions (count, sum, average, min, max, and more), filtering the item set, and sorting results. Common use cases include counting items per status, summing numbers by owner, or finding the average timeline duration across groups.

🚧
Precondition: Call get_board_info before using this tool to identify column IDs and types. For each column type in your aggregations or filters, call get_column_type_info with fetchMode: "guidelines" to understand valid aggregation functions and filter rules for that type.

When grouping, every column in groupBy must also appear in aggregations without a function (plain column reference). Human-readable labels for grouped columns appear under a LABEL_<columnId> field in the response.

Parameters

Parameter	Type	Required	Description
boardId	`number`	Yes	The ID of the board to calculate insights for.
aggregations	`array`	No	Array of aggregation objects, each with a `columnId` and an optional `function`. Supported functions include `COUNT`, `COUNT_ITEMS`, `SUM`, `AVERAGE`, `MIN`, `MAX`, `MEDIAN`, `LABEL`, `DATE_TRUNC_MONTH`, `DATE_TRUNC_WEEK`, and more. Columns in `groupBy` must also appear here without a function.
groupBy	`array`	No	Array of column IDs to group results by. All groupBy columns must also be present in `aggregations` without a function.
limit	`number`	No	Maximum number of result rows to return. Maximum 1000. Defaults to `1000`.
filters	`array`	No	Array of column filter objects (same structure as `get_board_items_page` filters). Narrows the item set before aggregation.
filtersOperator	`string`	No	Logical operator for combining multiple filters: `and` (default) or `or`.
orderBy	`array`	No	Array of sort objects with `columnId` and `direction` (`asc` or `desc`).

Example

Count items grouped by Status on board 18392419286:

{
  "boardId": 18392419286,
  "aggregations": [
    { "columnId": "status", "function": "COUNT_ITEMS" },
    { "columnId": "status" }
  ],
  "groupBy": ["status"]
}

The response returned 5 rows, one per status label, with item counts: Working on it (6), Done (4), Needs Review (2), Stuck (1), and blank/no-status (3). Each row included a LABEL_status field with the human-readable label and the hex color of that status.

Programmatic equivalent

Use the GraphQL API to achieve the same result. Board insights combine item filtering and aggregation, which in the API can be approximated with items_by_column_values and post-processing, or by fetching all items and aggregating client-side:

query {
  boards(ids: [18392419286]) {
    items_page(limit: 500) {
      items {
        id
        column_values(ids: ["status"]) {
          id
          text
          value
        }
      }
    }
  }
}

For full documentation, see Items.