Working with multi-level boards
A set of best practices for API usage on boards with more than two 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.
Summary of changes
- Multi-level boards support up to five layers of subitems and share a consistent column structure between parent items and subitems.
- Multi-level boards are excluded from the default
boardsquery. - Rollup columns are a new column capability for multi-level boards. They can contain both static and calculated values from child items.
- By default, the API returns only static values for Rollup columns; calculated values can be requested separately.
- Mutations and filtering introduce new behaviors you’ll need to handle when writing to or reading from multi-level boards.
Background
We are releasing two new entities in monday: multi-level boards and rollup columns.
Multi-level boards
A multi-level board is a new board type that supports up to five layers of subitems.
Initially, only project boards within thePortfolio solution will support this layout. When creating a Project board, a user can choose this type of layout. The classic board will still be the default when creating a regular board.
The subitem hierarchy of a multi-level board
Rollup columns
With multi-level boards in place, we also needed a way to summarize values across child items. This is where rollup columns come in.
Rollup is a new capability that can be enabled on number, date, and status columns on multi-level boards.
Columns with rollup can 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 it. If an 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.
Rollup logic on parent and child items
Estimated timeline
The following timelines differentiate between users' access to the feature and API access. This timeline is subject to change: refer to the API release notes for the most up-to-date information.
| Quarter | User changes | API changes |
|---|---|---|
| Q4 2025 | Alpha testing for a small group of users on Project boards. Developer accounts gain access. | API Version 2025-10: - boards query returns only classic boards by default.- hierarchy_type field is added to the boards object. |
| Q1 2026 | Multi-level boards are an option for all new boards. | API version 2026-04 released to RC. boards query returns both classic and multi-level boards by default. |
| Q2 2026 | No new changes | API Version 2026-04 released as the current default version. |
Backwards compatibility
To prevent breaking existing integrations, we’re introducing these features gradually:
- Until
2026-04, onlyclassicboards are returned by default in theboardsquery. Existing queries will behave as before. - All existing mutations still work. Rollup-specific restrictions (like blocked updates) only apply on multi-level boards.
✅ This means existing queries won’t break; you’ll only need to update code to take advantage of multi-level boards or rollups.
API changes
With the rollout schedule in mind, let’s walk through the specific API changes and how to adapt your existing queries.
Multi-level boards
| Multi-level boards | Classic boards | How to mitigate |
|---|---|---|
| Have up to five levels of subitems | One level of subitems only | Subitems can now have their own subitems. Boards have a deeper hierarchy than the previous two-level structure. |
All subitems are returned by subitems object, regardless of depth | Same behaviour | Use the parent_item field to calculate parent-child hierarchy. |
| Subitems have same column structure as parent items | Subitems have independent column structure | On multi-level boards, all items share the same column structure regardless of their depth. |
| Subitems board does not exist | Subitems can be queried on their own board | 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. |
Not returned by boards query, by default | Returned by default | For backward compatibility, the boards field will exclude multi-level boards by default. The boards field will return both classic and multi-level boards by default starting in version 2026-04. Use the argument hierarchy_types: [multi_level] to filter for classic or multi-level boards |
| Filters apply to parent items, by default | Same behaviour | Filters using the items_page or items_page_by_column_values queries will only apply to parent items by default. Pass the 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 | Same behaviour | The move_item_to_group, move_item_to_board, archive_item, delete_item, and duplicate_item mutations will apply to the target item and all its children. |
| Creating first subitem copies parent values | Same behavior | Creating the first subitem under a parent copies the parent’s values into the subitem (unless values are explicitly provided). Subsequent subitems trigger rollup recalculation but do not copy values. |
| Changing column values (rollup columns): Blocked when the item has ≥1 subitem (parent cell is calculated) | Same behavior | Remove all subitems to edit the parent (unblocks) or update child items instead. |
Rollup columns
| Change | Mitigation |
|---|---|
| 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. |
| Some rollup column types have subtypes to query specialized data | You can use the BatteryValue subtype on status rollup values to read the breakdown of statuses within a rollup. |
Columns have a capabilities field to show if they have rollup enabled | The capabilities field also shows what aggregation function the column is using (e.g., sum, mean, count, etc). |
create_column and update_column mutations have capabilities argument to add, remove, or change rollup function | If omitted, defaults apply: • On multi-level boards, numeric, date, timeline, and status columns are created with the calculated capability enabled • In all other cases, no capabilities are applied. To override this default on multi-level boards, pass an empty argument to create the column without capabilities. |
| Updating rollup column values will return an error | N/A |
| Filters apply across parent items and subitems, including rollup values | N/A |
Example queries
Use the following sample queries to get started with multi-level boards and rollup columns.
Multi-level board queries
Get items, subitems, and parent item relationship
This query gets items and their subitems. For some subitems, notice the parent_item field references other subitems. This means the subitem is nested under another subitem.
query getItemsAndSubitems {
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"
}
}
Using hierarchy_type to check board type
hierarchy_type to check board typeYou 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.
query getBoardsWithHierarchyType {
boards(hierarchy_types: [classic, multi_level] ) {
id
hierarchy_type
}
}
{
"data": {
"boards": [
{
"id": "118608050",
"hierarchy_type": "multi_level",
},
{
"id": "118608049",
"hierarchy_type": "classic",
}
]
}
}
Rollup column queries
Get values for both rollup and normal columns
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 getAllColumnValues {
boards (ids:9335825487) {
items_page {
items {
id
column_values (capabilities:[CALCULATED]) {
id
value
}
}
}
}
}
Get status column rollup values
The following query uses the BatteryValue subtype to get the breakdown of status values in a rollup cell.
query getBatteryRollupValues {
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 on the Column object contains rollup metadata. Use it to see the aggregation function used by the column (e.g., sum, mean, count, etc).
query getColumnRollupMetadata {
boards (ids:9571351437) {
columns (ids:"my_column") {
title
capabilities {
calculated {
function
calculated_type
}
}
}
}
}
Get help
For any questions or feedback, open a support ticket with our team! You can also post in our developer community and one of our experienced monday developers or staff members can help with your questions.
Updated 1 day ago