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.
All subitems are stored on an entirely separate board from their parent items. The subitems column on the parent board contains the IDs of the subitems linked to a given item. As such, in order to find your subitem board ID, you will first need to query the column_values() of the parent board's subitem column. This will return your subitem IDs which you can then use to query the boards field to find your subitem board ID.
You can learn more about subitems here.
Subitems Queries
Required scope: boards:read
New feature alert!
You can now query Subitems directly as part of querying the parent item. Find more info below.
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. You can find an example query below:
{
boards(ids: yourBoardId) {
id
name
items (limit: 10) {
id
name
column_values {
id
value
text
}
subitems {
id
name
column_values {
id
value
text
}
}
}
}
}
let query = "{ boards(ids: yourBoardId) { 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.
Arguments
If you query subitems as part of a Parent item, using the approach shown above, no arguments are currently supported.
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 | Field Description | Supported Arguments |
|---|---|---|
assets | The item's assets/files. | column_ids |
board | The board that contains this item. | |
column_values | The item's column values. | ids |
created_at | The item's create date. | |
creator | The item's creator. | |
creator_id | The unique identifier of the item creator. | |
group | The group that contains this item. | |
id | The item's unique identifier. | |
name | The item's name. | |
parent_item | The relevant parent item for the subitem. | assets |
state | The item's state (all / active / archived / deleted). | |
subscribers | The pulses's subscribers. | |
updated_at | The item's last update date. | |
updates | The item's updates. | limit |
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)));
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretApiKey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query { boards (ids: 1234567) { items { column_values { id }}}}"}'
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretApiKey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query { items(ids: "VALUE_RETURNED") { board { id }}}"}'
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).
NOTE
You can also use simple values in this mutation combined with regular values, or just simple values.
To check how to send the data for each column please see the Column Types Reference.
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)));
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretAPIkey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation{ create_subitem( parent_item_id: 1234567, item_name: \"new subitem\"){ id board { id }}}"}
Arguments for Create a Subitem
The following create_subitem() arguments define the new column's characteristics.
Argument | Description |
|---|---|
parent_item_id | The parent item's unique identifier. |
item_name | The new item's name. |
column_values | The column values of the new item. |
create_labels_if_missing | Creates status/dropdown labels if they're missing. Requires permission to change board structure. |
Subitem Webhooks
Want to be notified when a new subitem is created or an existing one is updated? You can use Webhooks for this. Check out our Webhooks documentation to learn more.
Do you 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 7 days ago