Items by column values
Removing the deprecated
items_by_column_values
objectThe deprecated
items_by_column_values
object will be removed in API version2023-10
. Use the newitems_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. |
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! 😎
Updated 9 days ago