Apps Framework DocsCommunityAPI Playground

Subitems

Suggest Edits

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.

FieldDescriptionSupported arguments
assets [Asset]The item's assets/files.column_ids [String]
board BoardThe board that contains this item.
column_values [ColumnValue]The item's column values.ids [String]
created_at DateThe item's create date.
creator UserThe item's creator.
creator_id String!The unique identifier of the item creator.
group GroupThe group that contains this item.
id ID!The item's unique identifier.
name String!The item's name.
parent_item ItemThe 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 StateThe item's state: all, active, archived, or deleted.
subscribers [User]!The pulses's subscribers.
updated_at DateThe 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 StringThe 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.

ArgumentDescription
parent_item_id IntThe parent item's unique identifier.
item_name StringThe new item's name.
column_values JSONThe column values of the new item.
create_labels_if_missing BooleanCreates 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