🚧
This is being deprecated in Jan 2024
The deprecated items_by_multiple_column_values object will be removed in API version 2023-10. Check out its replacement, the new items_page_by_column_values object, in version 2023-10!

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_multiple_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_multiple_column_values object via the API.

Queries

Required scope: boards:read

Querying items_by_multiple_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_multiple_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_multiple_column_values query.

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

query {
	items_by_multiple_column_values (board_id: 1234567890, column_id: "status", column_values: ["Working on it", "In progress"]) {
		id
		name
	}
}

let query = "query { items_by_multiple_column_values (board_id: 1234567890, column_id: \"status\", column_values: \"[\\\"Working on it\\\", \\\"In progress\\\"]\") { 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_multiple_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_values `[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_multiple_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 this 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.
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 `String`	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_multiple_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.
People	Search for values based on the name of the user, not the user ID (i.e. `["John Smith", "Jane Doe"]`). To search for multiple users assigned to a single item, pass their names as a list within a single index in the array (i.e. `["John Smith, Jane Doe"]`). The order does matter, so make sure to list the order of their names as it is seen in the GUI!
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_multiple_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.
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_multiple_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! 😎