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!

Queries

You can use the items_page_by_column_values query to search for items based on predefined column values via the API.

Required scope:boards:read
Returns an array containing metadata about one or a collection of specific items
Can only be queried directly at the root; can't be nested within another query

The items_page_by_column_values object allows you to combine multiple column values by sending an array. Unless specified otherwise, most column values will be used with an ANY_OF operator and only return items with all of the specified column values.

The following code sample returns 50 items from board 1234567890 that have a text column value of "This is a text column" AND a country column value of either the United States or Israel.

query {
  items_page_by_column_values(
    limit: 50
    board_id: 1234567890
    columns: [
      {
        column_id: "text"
        column_values: ["This is a text column"]
      }
      {
        column_id: "country"
        column_values: ["US", "IL"]
      }
    ]
  ) {
    cursor
    items {
      id
      name
    }
  }
}

The query will also return a cursor value that represents the position in the data set after returning 50 items. You can then use that string value to return the next 50 relevant items in the data set using the next_items_page object. After returning the next cursor value, you can continue the process to paginate through the entire data set.

query {
  next_items_page(
    cursor: "MSw5NzI4MDA5MDAsaV9YcmxJb0p1VEdYc1VWeGlxeF9kLDg4MiwzNXw0MTQ1NzU1MTE5"
    limit: 50
  ) {
    cursor
    items {
      id
      name
    }
  }
}

Arguments

You can use the following arguments to reduce the number of results returned in your items_page_by_column_values query.

Argument	Description	Supported Fields
board_id `ID!`	The specific board ID to return items for.
columns `[ItemsPageByColumnValuesQuery!]`	One or more columns and their values to search by. You can't use `columns` and `cursor` in the same request. We recommend using `columns` for the initial request and `cursor` for paginated requests.	column_id `String!` column_values `[String]!`
cursor `String`	An opaque token representing the position in the result set from which to resume fetching items. Use this to paginate through large result sets. You can't use `columns` and `cursor` in the same request. We recommend using `columns` for the initial request and `cursor` for paginated requests.
hierarchy_scope_config `String`	The board hierarchy configuration to filter by.
limit `Int!`	The number of items to return. The default is 25, but the maximum is 500.

Fields

You can use the following fields to specify what information your items_page_by_column_values query will return.

Field	Description
cursor `String`	An opaque cursor that represents the position in the list after the last returned item. When paginating through items, use this cursor to fetch the next set of items. There are no more items to fetch if the cursor is `null`.
items `[Item!]!`	The items associated with the cursor.

Supported and unsupported columns

This object supports specific column types, while some only have limited support.

Supported columns

The following columns are supported by items_page_by_column_values queries. Unless specified otherwise below, most columns accept either "" or null value to return items with empty column values.

Column Type	Notes
Checkbox	Pass true (e.g. `["1", "t", "true"]`) or false (e.g. `["false", "f", null]` value as a string. If you pass multiple values in the query, it will only return results based on the last value. For example:* `column_id: "check", column_values: ["1", "false", "f", "t"]` would return true values only.
Country	Pass the full name of the country as it appears in the UI as a string. You can also use the uppercase country code. For example:* `{column_id: "country", column_values: [null, "United States", "IL"]}`
Date	Pass just one string value in ISO-2 format (YYYY-MM-DD) with or without the hour, but please note that querying by the hour is not supported. For example:* `{column_id: "date", column_values: ["2023-08-01"]}`
Dropdown	Pass just one partial or whole string value to match the dropdown label. For example:* `{column_id: "dropdown", column_values: ["y Labe"]}` or `{column_id: "dropdown", column_values: ["My Label"]}`
Email	Pass the display text (label) values as strings. Please note that this column performs an exact match of the entire label textual value. For example:* `{column_id: "email", column_values: ["[email protected]", "[email protected]", null]}` or `{column_id: "email", column_values: ["Home email", "Work email", ""]}`
Hour	Pass the 24-hour value with or without the colon or one of these predefined values as a string: `MORNING` (6:00-12:00) `AFTERNOON`(12:00-16:00) `EVENING`(16:00-20:00) `NIGHT`(20:00-6:00) Please note that specifying an exact hour is only used to match the time to one of the predefined values. It will not return just the results with that specific value.For example: `{column_id: "hour", column_values: ["12:30", "EVENING", "0500", null]}` (returns all items in the afternoon, evening, or morning time ranges or those with empty values)
Link	Pass either the link or label value as it appears in the UI as a string. If there is both a link and label, use the label value. For example:* `{column_id: "link", column_values: ["https://www.google.com", "Link 1"}`
Long Text	Pass the entire text value as a string. This column searches for an exact match of the entire text value. For example:* `{column_id: "long_text", column_values: ["", "This is the entire value of a long text column. :)"]}`
Numbers	Pass the number value as a string. For example:* `{column_id: "numbers", column_values: ["", "-42"]}`
People	Pass a user's display name or user ID as a string. For example:* `{column_id: "people", column_values: ["565481", "Test user", null]}`
Phone	Pass an array of country names or codes as strings to return all of the properly formatted numbers corresponding to each country. You can also pass one full or partial number without any characters to return all items that contain the provided value. For example:* `{column_id: "phone", column_values: ["US", null, "Israel"]}` or `{column_id: "phone", column_values: ["665"]}` (returns all items containing a phone number with 665)
Status	Pass the label text value as seen in the UI as a string. For example:* `{column_id: "status", column_values: ["Done", "Working on it", null]}`
Text	Pass the entire text value as a string. This column searches for a case-insensitive match of the entire text value. For example:* `{column_id: "text", column_values: ["This is a text column.", null]}`
Timeline	Pass just one string value in ISO-2 format (YYYY-MM-DD) to return an exact match for the timeline's start date. For example:* `{column_id: "timeline", column_values: ["2023-07-01"]}` or `{column_id: "timeline", column_values: [""]}`
World Clock	Pass the label value as it appears in the UI as a string. For example:* `{column_id: "world_clock", column_values: ["", "Central"]}`

Unsupported columns

The following columns are not supported by items_page_by_column_values queries. If you query an unsupported column, you will receive an error.

Auto number
Color picker
Connect boards
Creation log
File
Formula
Item ID
Last updated
Location
Mirror
Rating
Tags
Time tracking
Vote