Items by multiple column values

๐Ÿšง

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.

ArgumentDescription
board_id Int!The specific board IDs to return items for.
column_id String!The specific column IDs to return items for.
column_type StringThe 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 IntThe number of items to return.
page IntThe page number to return. Starts at 1.
state StateThe 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.

FieldDescriptionSupported arguments
assets [Asset]The item's assets/files.assets_source AssetsSource
column_ids [String]
board BoardThe board that contains this item.
column_values [ColumnValue]The item's column values.ids [String]
created_at DateThe item's creation date. The list will appear in chronological order with the oldest dates first.
creator UserThe 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 GroupThe item's group.
id ID!The item's unique identifier.
name String!The item's name.
parent_item ItemA subitem's parent item. If used for a parent item, it will return null.
relative_link StringThe item's relative path.
state StateThe item's state: all, active, archived, or deleted.
subitems [Item]The item's subitems.
subscribers [User]!The item's subscribers.
updated_at StringThe 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 typeNotes
Country
DateSearch 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
NumbersSearch 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.
PeopleSearch 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
StatusSearch 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 ClockSearch 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 typeNotes
DependencySupports individual items only.
DropdownWill 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.
FileWill 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.
LinkWill 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.
TimelineYour 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โ€
WeekThe 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! ๐Ÿ˜Ž