Multi-level boards: API guide
A set of best practices to help app developers adapt to boards with more than 2 levels of subitems
This release introduces a new board type that enables multiple levels of subitems and a new rollup column. This document outlines the new features and breaks down the API changes you'll need to adapt to.
Background and context
We are releasing two new entities in monday: multi-level boards and rollup columns.
Multi-level boards
A multi-level board is a new type of board that supports up to 5 layers of subitems. When creating a board, a user must choose this type of board. The classic board will still be the default when creating a new board.
Rollup columns
Rollup is a new capability that can be enabled on number, date, and status columns on multi-level boards.
Columns with rollup have the ability to summarize the data in their child items. An individual rollup cell will either contain static data or summarize (roll up) the data of items below them. If a item is a parent, the cell will contain the summary of its child items. If the item has no children, the cell will contain a value.
API changes
The following section explains the API changes with this release and how to mitigate each one.
Multi-level boards
Subitem hierarchy is now up to 5 levels
Subitems can now have their own subitems. Boards have a deeper hierarchy than the previous two-level structure.
All subitems, regardless of depth, will be returned in the subitems object. Use the parent_item field to build the correct hierarchy.
{
boards(ids: 9335825487) {
items_page (limit:1) {
items {
id
name
subitems {
id
name
parent_item {
id
name
}
}
}
}
}
complexity {
query
}
}
{
"data": {
"boards": [
{
"items_page": {
"items": [
{
"id": "9778025723",
"name": "Partner Integration Campaign",
"subitems": [
{
"id": "9778032507",
"name": "Recruit partners",
"parent_item": {
"id": "9778025723",
"name": "Partner Integration Campaign"
}
},
{
"id": "9778033036",
"name": "Technical discovery with partners",
"parent_item": {
"id": "9778025723",
"name": "Partner Integration Campaign"
}
},
{
"id": "9778038091",
"name": "List of potential partners",
"parent_item": {
"id": "9778032507",
"name": "Recruit partners"
}
},
{
"id": "9778043578",
"name": "Email reachout 1",
"parent_item": {
"id": "9778032507",
"name": "Recruit partners"
}
},
{
"id": "9778043946",
"name": "Email reachout 2",
"parent_item": {
"id": "9778032507",
"name": "Recruit partners"
}
},
{
"id": "9778049250",
"name": "Write technical documentation",
"parent_item": {
"id": "9778033036",
"name": "Technical discovery with partners"
}
},
{
"id": "9778049867",
"name": "Build intro deck",
"parent_item": {
"id": "9778033036",
"name": "Technical discovery with partners"
}
},
{
"id": "9801839208",
"name": "Google research",
"parent_item": {
"id": "9778038091",
"name": "List of potential partners"
}
},
{
"id": "9801839457",
"name": "Validation",
"parent_item": {
"id": "9778038091",
"name": "List of potential partners"
}
},
{
"id": "9801842306",
"name": "Export to CSV",
"parent_item": {
"id": "9801839208",
"name": "Google research"
}
},
{
"id": "9801845518",
"name": "Document the process for next time",
"parent_item": {
"id": "9801839208",
"name": "Google research"
}
}
]
}
]
}
}
],
"complexity": {
"query": 1231
}
},
"extensions": {
"request_id": "a1a0b652-2b08-9948-9f02-1dc6e7817a70"
}
}
Subitems have the same columns as parent items
On multi-level boards, all items share the same column structure regardless of their depth.
Subitems board does not exist for multi-level boards
On classic boards, there was a hidden "subitems board" that contained the subitems for a board. This does not exist on multi-level boards. All subitems from the board are accessible via the subitems object field on the items object.
Multi-level boards are not returned in boards by default (initially)
boards by default (initially)For backward compatibility, the boards field will exclude multi-level boards by default in API versions 2026-01 and earlier.
In 2026-04 the boards field will return both classic and multi-level boards by default (releasing April 2026).
You can filter boards for classic and multi-level boards
boards for classic and multi-level boardsThe boards field now takes an optional hierarchy_types argument. It lets you filter for only classic or multi-level boards (or both).
You can use the hierarchy_type field on the Board object type to check if a board is multi-level. This field has two possible values: multi_level and classic.
{
boards(hierarchy_types: [classic, multi_level] ) {
id
hierarchy_type
}
}
{
"data": {
"boards": [
{
"id": "118608050",
"hierarchy_type": "multi_level",
},
{
"id": "118608049",
"hierarchy_type": "classic",
}
]}
}
Filters apply to parent items by default
Filters using the items_page or items_page_by_column_values queries will only apply to parent items by default.
You can pass an optional hierarchy_scope_config argument with the value allItems to apply the filter on both items and subitems. If a subitem matches a a filter, it will be returned with its parent items too.
Archiving, deleting, and duplicating items affect all child subitems as well
The archive_item delete_item and duplicate_item mutations now archive, delete, and duplicate the item as well as all its subitems.
Rollup columns
Rollup column values (cells) are not returned by default
By default, rollup values will not be returned by the column_values field. Our API will return null for these values.
To return rollup values, you must pass the argument (capabilities: [CALCULATED]). This will return both rollup and static values:
query {
boards (ids:9335825487) {
items_page {
items {
id
column_values (capabilities:[CALCULATED]) {
id
value
}
}
}
}
}
Status column values
You can use the BatteryValue subtype on status rollup values to read the breakdown of statuses within a rollup.
To use it, include the ...on BatteryValue fragment when querying the column_values object:
{
boards(ids: [100]) {
items_page {
items {
id
name
column_values(ids: ["status"], capabilities:[CALCULATED]) {
id
value
... on BatteryValue {
battery_value {
key, # the key of the status
count # number of occurances
}
}
}
}
}
}
}
Columns have a capabilities field to show if they have rollup enabled
capabilities field to show if they have rollup enabledThe capabilities field also shows what aggregation function the column is using (eg sum, mean, count, etc).
{
boards (ids:9571351437) {
columns (ids:"my_column") {
title
capabilities {
calculated {
function
calculated_type
}
}
}
}
}
Updating column values
Updating any rollup values will return an error.
Filtering rollup values
Filters match to rollup values by default.
Updated 17 days ago