Apps Framework DocsCommunityAPI Playground

Items by column values

Suggest Edits

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.

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_value 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_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 the 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.
state StateThe item's state: all, active, archived, or deleted.
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 DateThe 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 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.
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_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.
PeopleWill 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.
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_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 2 days ago