monday.com items are a core object in the platform. Items are the objects that hold the actual data within the board, to better illustrate this, you can think of a board as a table and an item as a single row in that table.

Items queries

Required scope: boards:read

You can use items at the root of your query or nest them within another query. Querying items directly returns all items across the account. You can also nest items within a boards query to return all items from a specific board.

Check out this Postman request to get items from a board!

query {
    items (ids: [12345678, 23456789, 34567890]) {
        name
    }
}

let query = "query { items (ids: [12345678, 23456789, 34567890]) { name }}";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Please note that you cannot return more than 100 items per query when using items at the root. To adjust your query, try only returning items on a specific board, nesting items inside a boards query, looping through the boards on your account, or querying less than 100 items at a time.

Arguments

The following item arguments can reduce the number of items returned.

Fields

Items contain the actual data within the boards. Each item contains columns in which the different values are stored.

The following fields will determine what is returned from your items query. Some fields will have their own arguments.

Additional rate limit

Queries that do not specify any item IDs, board, or group can only be made one time every 2 minutes. For example:

query {
   items {
      id
      name
   }
}

Queries that specify more than 100 item IDs can only be made one time every 2 minutes. For example:

query {
   items (ids: [1, 2, 3, ..., 101]) {
      id
      name
   }
}

These two query types share this limit. For example, if I run a query that does not specify item IDs, I will have reached the limit and I will not be able to run a query that specifies more than 100 item IDs in the same two minutes, and vice versa.

We will no longer support these queries beginning October 3rd, 2022. You can read more about these changes here.

Items mutations

Required scope: boards:write

Create an item

This method allows you to create a new item. After the mutation runs you can query back all the item data as shown in the querying items section above.

The data of each item is stored in the board’s columns, 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_item (board_id: 1234567, group_id: "today", item_name: "new item") {
        id
    }
}

let query = "mutation { create_item (board_id: 1234567, group_id: \"today\", item_name: \"new item\") { id }}";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

We've compiled the requests to create an item and create an item using variables in a Postman collection.

Arguments for create an item

The following arguments define the new item's characteristics.

🚧

NOTE

To change the item name of an existing item, check out the Item Name (First Column) article. It will require you to utilize the change_column_value() mutation with a JSON string value.

Create a subitem

This method allows you to create a new subitem for any parent item. After the mutation runs you can query back all the item data as shown in the querying items section above.

Subitems are technically created under a different board, which is NOT the same board as the parent item's board. You can query the identifier of this board through the regular board resolver of the subitem. Using this board ID and subitem ID you can apply any action to the subitem as you would to a regular item (i.e. archive it, delete, change column_values, etc).

📘

NOTE

For creating subitems via the API, the board should already have a subitems column, or at least one subitem created, otherwise you will receive an error.

mutation {
    create_subitem (parent_item_id: 1234567, item_name: "new subitem") {
        id
        board {
            id
        }
    }
}

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' : 'YOUR_API_KEY_HERE'
   },
   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 subitem's characteristics.

Clear an item's updates

This mutation allows one to clear all updates on a specific item, including replies and likes. After the mutation runs you can query back the item data as shown in the querying items section above.

mutation {
    clear_item_updates (item_id: 20178755) {
        id
    }
}

let query = "mutation { clear_item_updates (item_id: 20178755) { id }}";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments for clear an item's updates

The following argument determines which item's updates are cleared.

Move item to group

This mutation allows one to move an item between groups in the same board. After the mutation runs you can query back the item data as shown in the querying items section above.

mutation {
    move_item_to_group (item_id: 1234567, group_id: "today") {
        id
    }
}

let query = "mutation { move_item_to_group (item_id: 1234567, group_id: \"today\") { id }}";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments for move item to group

The following arguments determine which item is moved to which group.

Archive an item

This mutation allows you to archive a single item. After the mutation runs you can query back the item data as shown in the querying items section.

mutation {
    archive_item (item_id: 12345678) {
        id
    }
}

let query = "mutation {archive_item (item_id: 12345678) { id }}";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments for archive an item

The following argument determines which item is archived.

Delete an item

This mutation allows you to delete a single item. After the mutation runs you can query back the remaining items data as shown in the querying items section above.

mutation {
    delete_item (item_id: 12345678) {
        id
    }
}

let query = "mutation { delete_item (item_id: 12345678) { id }}";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments for delete an item

The following argument determines which item will be deleted.

Duplicate an item

This mutation allows you to duplicate a single item. After the mutation runs you can query back the remaining items data as shown in the querying items section above.

mutation {
    duplicate_item (board_id: 1234567, item_id: 12345678, with_updates: true){
        id
    }
}

let query = "mutation { duplicate_item (board_id: 1234567, item_id: 12345678, with_updates: true) { id }}";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments for duplicate an item

The following arguments determine which item and how it will be duplicated.

📘

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!