Items By Column Values

Required scope: boards:read

monday.com items are another core object in the platform. Items are the objects that hold the actual data within the board, to better illustrate this, you can think of a board as a table and an item as a single row in that table.

You can learn more about this object type here.

Querying items_by_column_values() searches for items based on predefined column values and returns data about these specific items.

You can only use items by column values at the root of your query. They cannot be nested within another query.

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

let query = "query { items_by_column_values (board_id: 1234567, 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)));

curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: yourSecretKey' \
--header 'Content-Type: application/json' \
--data-raw '{"query": "query { items_by_column_values (board_id: 1234567, column_id: "date", column_value: "2019-02-06") { id name } }"}'

You can find the Postman request to query items by column values here.

Arguments

The following items_by_column_values() arguments can reduce the number of item returned.

Unlike other queries, when querying items by their column values, there are some arguments that must be included, and some arguments that are optional.

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

Fields

The following fields will determine what information is returned from your items_by_column_values() queries. Some fields will have their own arguments.

The fields available for items_by_column_values() are exactly the same as the fields available in Items.

Field	Field Definition	Arguments
assets `[Asset]`	The item's assets/files.	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 reverse chronological order with the most recent dates first.
creator `User`	The item's creator.
creator_id `String!`	The unique identifier of the user who created the item.
group `Group`	The group that contains this item.
id `ID!`	The item's unique identifier.
name `String!`	The item's name reflected in the first column of any board.
parent_item `Item`	The relevant parent item of a subitem. If used for a parent item, it will return `null`.	limit `Int` page `Int` ids `[Int]` newest_first `Boolean` exclude_nonactive `Boolean`
state `State`	The item's state: all, active, archived, or deleted.
subscribers `[User]!`	The user IDs of the users who are subscribed to this item.
updated_at `String`	The date when the item was last updated.	limit `Int` page `Int`
updates `[Update]`	The item's updates.	limit `Int` page `Int`
email `String!`	The item's email.
subitems `[Item]`	The item's subitems.	limit `Int` page `Int` ids `[Int]` newest_first `Boolean` exclude_nonactive `Boolean`
relative_link `String`	The item's relative path.

Pagination

The maximum amount of items that can be retrieved using pagination is 10,000. You can return up to 10 pages with a maximum of 1,000 items each.

Supported columns

The following columns support the items_by_column_values() queries. In addition, you can find provided notes about the column types.

Supported Columns	Notes
Text
Long Text
Status	Search for values based on Label (text within the cell), and not on index. (i.e., `“Working on it”`, `“Done”` and not index:1)
Numbers	Search for the number as a string, and not as 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;
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
Phone
Country
World Clock	Search for the text value of the column. For example, `“Europe/Berlin”`;
Email

Limited support columns

The following columns provide limited support for the items_by_column_values() queries.

Column type	Notes
People column	Will only return results for items where a single user is assigned. Doesn’t support arrays of users, will only return results based on actual user name and not User ID;
Dropdown column	Will only return a single value that 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.
Timeline column	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”` Thus, you will have to search for the same date twice, separated by a dash. If you have different dates, they have to be formatted in a similar fashion: `“2021-03-01 - 2021-03-02”`
File column	Will return a single file as a result, but not multiple files. You will need to use the full item name, together with the extension. If your filename is `1` and the extension is `.jpg` (an image), you will need to search for `1.jpg` for the correct results.
Week column	The text version of the week should be used. For example, if your Week column is set to a week from February-22, 2021 to February 28, 2022, the query should look like this: `“2021-02-22 - 2021-02-28”` Then, you’ll be able to get the item;
Dependency column	Supports individual items only;
Link column	Will return results based on the `Display text` of the Link column, and not the actual URL. If those are different, the display text will be used.

Not supported columns

The following columns are not supported by the items_by_column_values() queries.

Tags: not supported
Connect Boards: not supported
Mirrored columns: not supported
Checkbox column: not supported
Location column: not supported
Rating: not supported
Color picker: not supported
AutoNumber: not supported
Formula: not supported
Item ID: not supported
Last Updated: not supported
Creation Log: not supported
Vote: not supported
Time Tracking: not supported

Note

When creating an item or adding a value to a column, the new value for the column might take up to 30 seconds to be available for retrieving using items_by_column_values().

📘
Do you have questions?
Join our developer community! You can share your questions and learn from fellow users and monday.com product experts.
Don’t forget to search before opening a new topic!

Arguments

Fields

Pagination

Supported columns

Limited support columns

Not supported columns

Note

📘Do you have questions?

📘
Do you have questions?