The monday.com aggregate API enables you to read board data using groupings and aggregation functions.

The types below are used by the aggregate query and are not independently queryable.

AggregateQueryInput

An object containing the aggregation query to execute.

Field	Type	Description
from	`AggregateFromTableInput!`	The data source for the aggregation.
group_by	`[AggregateGroupByElementInput!]`	The fields to group results by. The default limit per group is 1,000.
limit	`Int`	The maximum number of result groups to return. Only applies when using `group_by`.
query	`ItemsQuery`	The filters for the items being aggregated. Without it, all items will be included.
select	`[AggregateSelectElementInput!]!`	The fields or functions to return.

AggregateFromTableInput

An object containing the source table and its ID for the aggregation query.

Field	Type	Description	Enum Values
id	`ID!`	The unique identifier of the source (e.g., board ID).
type	`AggregateFromElementType!`	The source type.	`TABLE`

AggregateGroupByElementInput

An object containing the item limit and column to group results by.

Field	Type	Description
column_id	`String!`	The unique identifier of the column to group results by. Can also be an alias from a transformative function.
limit	`Int`	The number of groups to return. The default is 1,000.

AggregateSelectElementInput

An object containing the fields or functions to return.

Field	Type	Description	Enum Values
as	`String!`	The field's alias in the result set. For columns used in `group_by`, the alias must match the `column_id` in the `group_by` array.
column	`AggregateSelectColumnInput`	The column to select from the source. Required if type is `COLUMN`.
function	`AggregateSelectFunctionInput`	The function to apply to the specified fields. Required if type is `FUNCTION`.
type	`AggregateSelectElementType!`	Whether this element is a column reference or a function call.	`COLUMN` `FUNCTION`

AggregateSelectColumnInput

An object containing the column to select from the source.

Field	Type	Description
column_id	`String!`	The column's unique identifier.

AggregateSelectFunctionInput

An object containing the function to apply to the specified fields.

Field	Type	Description	Enum Values
function	`AggregateSelectFunctionName!`	The function name.	`AVERAGE` `BETWEEN` `CASE` `COLOR` `COUNT` `COUNT_DISTINCT` `COUNT_ITEMS` `COUNT_KEYS` `COUNT_SUBITEMS` `DATE` `DATE_TRUNC_DAY` `DATE_TRUNC_MONTH` `DATE_TRUNC_QUARTER` `DATE_TRUNC_WEEK` `DATE_TRUNC_YEAR` `DURATION_RUNNING` `END_DATE` `EQUALS` `FIRST` `FLATTEN` `HOUR` `ID` `IS_DONE` `LABEL` `LEFT` `LENGTH` `LOWER` `MAX` `MEDIAN` `MIN` `MIN_MAX` `NONE` `ORDER` `PERSON` `PHONE_COUNTRY_SHORT_NAME` `RAW` `START_DATE` `SUM` `TRIM` `UPPER`
params	`[AggregateSelectElementInput!]`	The arguments passed into the function. For column-based functions (e.g., `SUM`, `AVERAGE`), pass a `COLUMN` type element with the target `column_id`. Not required for item-level functions like `COUNT_ITEMS`.

AggregateResultSet

An object containing the result of the aggregate query. When using group_by, each AggregateResultSet represents one group.

Field	Type	Description
entries	`[AggregateResultEntry!]`	A list of results, each representing either a grouping key or an aggregated value.

AggregateResultEntry

An object containing the field's name and value.

Field	Type	Description	Possible Types
alias	`String`	The name of the field, as defined using the `as` field. Used to map the result to its corresponding expression.
value	`AggregateResult`	The value returned for the given alias. Can represent a group-by key or an aggregated metric.	`AggregateBasicAggregationResult` `AggregateGroupByResult`

AggregateBasicAggregationResult

An object containing the result of the aggregation function.

Field	Type	Description
result	`Float`	The numeric result from the aggregation function. Returns `null` when all values in the group are null or the column is empty.

AggregateGroupByResult

An object containing the group-by value. The value field returns a JSON value whose type depends on the source column.

🚧
Breaking change in API versions 2026-04 and later: The value_string, value_int, value_float, and value_boolean fields have been removed and replaced by a single unified value field of type JSON. Consumers that reference the old typed fields must migrate to the value field and handle type coercion on the client side.

Field	Type	Description
value	`JSON`	The group-by value. Type varies: strings for text/status (hex codes), booleans for checkboxes, numbers for dates (epoch ms).

API Version	Available Fields	Notes
Before `2026-04`	`value_string`, `value_int`, `value_float`, `value_boolean`	Separate typed fields
`2026-04` and later	`value` (`JSON`)	Unified field — handle type coercion client-side

📘
Group by value format reference

Column Type Value Format Example
Status Hex color code "#00c875"
People Person ID string "person-12345"
Checkbox Boolean true
Text Plain string "Category A"
Date Epoch timestamp (ms) 1768435200000
Numbers Numeric value 42