🚧
Removing the deprecated items_by_column_values object
The deprecated items_by_column_values object will be removed in API version 2023-10. Use the new items_page_by_column_values object instead.

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_by_column_values API so you know how to access items based on predefined column values data. This document will walk you through the available queries to read the items_by_column_values object via the API.

Queries

Required scope: boards:read

Querying items_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_by_column_values directly at the root, so it can't be nested within another query. Please note that when creating an item or adding a value to a column, you may have to wait around 30 seconds to retrieve the new value using the items_by_column_values query. Additionally, you can only retrieve up to 10,000 items using pagination. You can return up to 10 pages with a maximum of 1,000 items each.

Check out this query in action in our Postman library or follow along with these code samples!

query {
  items_by_column_values (board_id: 1234567890, column_id: "date", column_value: "2019-02-06") {
    id
    name
  }
}

let query = "query { items_by_column_values (board_id: 1234567890, column_id: \"date\", column_value: \"2019-02-06\") { id 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)));

Arguments

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

Argument	Description
board_id `Int!`	The specific board IDs to return items for.
column_id `String!`	The specific column IDs to return items for.
column_type `String`	The column type to search by. For example, a status column's type is `color`.
column_value `String!`	The column value to search items by. You can use text values for the search.
limit `Int`	The number of items to return.
page `Int`	The page number to return. Starts at 1.
state `State`	The item's state: all, active, archived, or deleted. The default state is active.

Fields

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

Field	Description	Supported arguments
assets `[Asset]`	The item's assets/files.	assets_source `AssetsSource` column_ids `[String]`
board `Board`	The board that contains the item.
column_values `[ColumnValue]`	The item's column values.	ids `[String]`
created_at `Date`	The item's creation date. The list will appear in chronological order with the oldest dates first.
creator `User`	The item's creator.
creator_id `String!`	The unique identifier of the user who created the item. Returns `null` if the item was created by default on the board.
email `String!`	The item's email.
group `Group`	The item's group.
id `ID!`	The item's unique identifier.
name `String!`	The item's name.
state `State`	The item's state: all, active, archived, or deleted.
parent_item `Item`	A subitem's parent item. If used for a parent item, it will return `null`.
relative_link `String`	The item's relative path.
state `State`	The item's state: all, active, archived, or deleted.
subitems `[Item]`	The item's subitems.
subscribers `[User]!`	The item's subscribers.
updated_at `Date`	The item's last updated date.
updates `[Update]`	The item's updates.	limit `Int` page `Int`

Supported, limited support, and unsupported columns

Supported columns

The following columns support items_by_column_values queries.

Column type	Notes
Country
Date	Search for `YYYY-MM-DD` values. For example, March 1st, 2021, would be `2021-03-01` when making the request. Dates with times are not supported.
Email
Hour
Long Text
Numbers	Search for the number as a string, not an integer. For example, if you’d like to find all items with a 15 value, search for `“15”`. This also supports searching for `0` values, but will not return empty cells.
Phone
Status	Search for values based on the label (text within the cell), not on the index. (i.e., `“Working on it”`, `“Done”` and not index:1)
Text
World Clock	Search for the text value of the column. For example, `“Europe/Berlin”`

Limited support columns

The following columns provide limited support for items_by_column_values queries.

Column type	Notes
Dependency	Supports individual items only.
Dropdown	Will only return a single value you search. If you have an item with Dropdown labels, such as `“1”` and `“2”`, a query for “1, 2” will return a null object. If you have an item with only “1” selected, the results will show correctly.
File	Will return a single file, not multiple files. You will need to use the full item name with the extension. If your file name is `1` and the extension is `.jpg` (an image), you will need to search for `1.jpg`.
Link	Will return results based on the `Display text` of the link column, not the actual URL. If those are different, the display text will be used.
People	Will only return results for items where a single user is assigned. Doesn’t support arrays of users and returns results based on the actual user name, not the user ID.
Timeline	Your query has to match the values shown in the `column_values { text` results. For example, if you have a timeline set to a single date, the Start and End date will be considered the same date: `“2021-02-24 - 2021-02-24”`. You will have to search for the same date twice, separated by a dash. If you have different dates, they have to be formatted similarly: `“2021-03-01 - 2021-03-02”`
Week	The text version of the week should be used. For example, a query for a week column from February 22, 2021, to February 28, 2021, should look like this: `“2021-02-22 - 2021-02-28”`

Unsupported columns

The following columns are not supported by items_by_column_values queries.

Auto number
Checkbox
Color picker
Connect boards
Creation log
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! 😎