Subitems
Subitems are special items that are "nested" under the items on your board. They can be accessed via the subitem column which can be added either from the columns center, or by right-clicking an item to expose its dropdown menu.
Subitems queries
Required scope: boards:read
Subitems are available for querying through parent items. They must be nested within another query, like a board. You cannot use them at the root of your query.
The subitems object will include all of the Item fields.
{
boards(ids: 123456789) {
id
name
items (limit: 10) {
id
name
column_values {
id
value
text
}
subitems {
id
name
column_values {
id
value
text
}
}
}
}
}
let query = "{ boards(ids: 123456789) { id name items (limit: 10) { id name column_values { id value text } subitems { id name column_values { id value text } } } } } ";
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YourSuperSecretApiKey'
},
body: JSON.stringify({
'query': query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YourSuperSecretApiKey'
},
body: JSON.stringify({
'query': query2
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Querying sub-items and complexity
When making a query for subitems as part of items, your subitems query becomes nested. This may lead to an increase in your query's complexity rating. To have more control over the complexity rating of those queries, we currently recommend limiting the number of items you retrieve.
You can find more about complexity rate limits here.
Fields
Subitems, like Items, store data within their columns.
The following fields will determine what is returned from your subitems query. Some fields will have their own arguments.
Field | Description | Supported arguments |
---|---|---|
assets [Asset] | The item's assets/files. | column_ids [String] |
board Board | The board that contains this item. | |
column_values [ColumnValue] | The item's column values. | ids [String] |
created_at Date | The item's create date. | |
creator User | The item's creator. | |
creator_id String! | The unique identifier of the item creator. | |
group Group | The group that contains this item. | |
id ID! | The item's unique identifier. | |
name String! | The item's name. | |
parent_item Item | The relevant parent item of a subitem. If used for a parent item, it will return null . | limit Int page Int ids [Int] newest_first Boolean exclude_nonactive Boolean |
state State | The item's state: all, active, archived, or deleted. | |
subscribers [User]! | The pulses's subscribers. | |
updated_at Date | The item's last update date. | |
updates [Update] | The item's updates. | limit Int page Int |
email String! | The item's email. | |
subitems [Item] | The item's subitems. | |
relative_link String | The item's relative path. |
There is a different method of querying for sub-item data as well. Here's an example of the method, which involves using multiple queries. In the first, you query the parent item's subitems
column in order to get the associated sub-item IDs, and then query those for their values.
// This query will return the value of your subitem column, which will include your subitem IDs
query {
boards (ids: 1234567) {
items {
column_values (ids: "subitems2"){
value
}
}
}
// This query will return the board ID using your subitem ID
query {
items(ids: "VALUE_RETURNED"){
board {
id
}
}
}
let query = "query { boards(ids: 1234567) { items { column_values { id }}}}";
let query2 = "query { items(ids: "VALUE_RETURNED"){ board { id }}}";
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YourSuperSecretApiKey'
},
body: JSON.stringify({
'query': query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YourSuperSecretApiKey'
},
body: JSON.stringify({
'query': query2
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Subitems mutations
Required scope: boards:write
Create a subitem
This method allows you to create a new subitem. After the mutation runs you can query back all the subitem data as shown in the querying subitems section above.
The data of each subitem is stored in the subitem board columns (same as items), each of which holds a particular piece of information. Each column has a certain type, and different column types expect a different set of parameters to update their values. When sending data to a particular column, use a JSON-formatted string (if you’re using Javascript, you can use JSON.stringify()
to convert a JSON object into a string).
You can also use simple values in this mutation or combine them with regular values. Check out our column types reference to see how to send data for each column.
mutation {
create_subitem (parent_item_id: 1234567, item_name: "new subitem") {
id
board {
id
}
}
}
const fetch = require('node-fetch')
let query = "mutation{ create_subitem (parent_item_id: 1234567, item_name: \"new subitem\"){ id board { id }}}"
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YourSuperSecretAPIkey'
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments for create a subitem
The following arguments define the new column's characteristics.
Argument | Description |
---|---|
parent_item_id Int | The parent item's unique identifier. |
item_name String | The new item's name. |
column_values JSON | The column values of the new item. |
create_labels_if_missing Boolean | Creates status/dropdown labels if they're missing. Requires permission to change board structure. |
We've compiled the requests to create a subitem and create a subitem using variables in a Postman collection.
Have questions?
Join our developer community! You can share your questions and learn from fellow users and monday.com product experts.
Don’t forget to search before opening a new topic!
Updated 5 days ago