Items are core objects in the monday.com platform that hold the actual data within the board. To better illustrate the platform, imagine that each board is a table and an item is a single row in that table. Now take one row, fill it with whatever information you'd like, and you now have an item!

As a developer working with monday.com, it is important to familiarize yourself with the items_page_by_column_values API so you know how to access items based on predefined column values. This document will walk you through the available queries to read the items_page_by_column_values object via the API.

Queries

Required scope: boards:read

Querying items_page_by_column_values will search for items based on predefined column values and return metadata about these specific items. This method accepts various arguments and returns an array.

You can only query items_page_by_column_values directly at the root, so it can't be nested within another query. This object supports specific column types, while some only have limited support. The supported and unsupported section below outlines the support for each column and which values to send for each.

The items_page_by_column_values object allows you to combine multiple column values by sending an array. Unless specified otherwise, most column values will be used with an ANY_OF operator and only return items with all of the specified column values.

The following code sample returns 50 items from board 1234567890 that have a text column value of "This is a text column" AND a country column value of either the United States or Israel.

query {
  items_page_by_column_values (limit: 50, board_id: 1234567890, columns: [{column_id: "text", column_values: ["This is a text column"]}, {column_id: "country", column_values: ["US", "IL"]}]) {
    cursor
    items {
      id
      name
    }
  }
}

let query = "query { items_page_by_column_values (limit: 50, board_id: 1234567890, columns: [{column_id: \"text\", column_values: [\"This is a text column\"]}, {column_id: \"country\", column_values: [\"US\", \"IL\"]}]) { cursor items { id name }}}";

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

The query will also return a cursor value that represents the position in the data set after returning 50 items. You can then use that string value to return the next 50 relevant items in the data set using the next_items_page object. After returning the next cursor value, you can continue the process to paginate through the entire data set.

query {
  next_items_page (cursor: "MSw5NzI4MDA5MDAsaV9YcmxJb0p1VEdYc1VWeGlxeF9kLDg4MiwzNXw0MTQ1NzU1MTE5", limit: 50) {
    cursor
    items {
      id
      name
    }
  }
}

let query = "query { next_items_page (cursor: \"MSw5NzI4MDA5MDAsaV9YcmxJb0p1VEdYc1VWeGlxeF9kLDg4MiwzNXw0MTQ1NzU1MTE5\", limit: 50) { cursor items { id name }}}";

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

Arguments

You can use the following argument(s) to reduce the number of results returned in your items_page_by_column_values query. Unlike other queries, some arguments are required.

Fields

You can use the following field(s) to specify what information your items_page_by_column_values query will return. Please note that some fields will have their own arguments.

Supported and unsupported columns

Supported columns

The following columns are supported by items_page_by_column_values queries. Unless specified otherwise below, most columns accept either "" or null value to return items with empty column values.

Unsupported columns

The following columns are not supported by items_page_by_column_values queries. If you query an unsupported column, you will receive an error.

• Auto number
• Color picker
• Connect boards
• Creation log
• File
• Formula
• Item ID
• Last updated
• Location
• Mirror
• Rating
• Tags
• Time tracking
• Vote

📘

Join our developer community!

We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎