Items by multiple column values 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.

Items by multiple column values queries

Required scope: boards:read

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

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

query {
    items_by_multiple_column_values (board_id: 1234567, column_id: "status5", column_values: ["Working on it", "In progress"]) {
let query = "query { items_by_multiple_column_values (board_id: 2904502171, column_id: \"status\", column_values: \"[\\\"Working on it\\\", \\\"In progress\\\"]\") { id name } }";

fetch ("", {
  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)));

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


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

The following arguments can reduce the number of items returned.

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


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

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

assets [Asset]The item's assets/files.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.
creator UserThe item's creator.
creator_id String!The unique identifier of the user who created the item.
group GroupThe 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 ItemThe 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 StateThe item's state: all, active, archived, or deleted.
subscribers [User]!The user IDs of the users who are subscribed to this item.
updated_at StringThe date when the item was last updated.
updates [Update]The item's updates.limit Int
page Int
email String!The item's email.
subitems [Item]The item's subitems.
relative_link StringThe item's relative path.

Supported columns

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

Supported ColumnsNotes
Long Text
StatusSearch for values based on Label (text within the cell), and not on index. (i.e., [“Working on it”, “Done”] and not index:1)
NumbersSearch for numbers as strings, and not as integers. 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
DateSearch for YYYY-MM-DD values. For example, March 1st, 2021, would be 2021-03-01 when making the request
PeopleSearch for values based off of 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!
World ClockSearch for the text value of the column. For example, “Europe/Berlin”

Limited support columns

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

Column typeNotes
People columnWill 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 columnWill 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 columnYour 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 columnWill 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 columnThe 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 columnSupports individual items only
Link columnWill 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.

Not supported columns

The following columns are not supported by the items_by_multiple_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


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_multiple_column_values().


Have questions?

Join our developer community! You can share your questions and learn from fellow users and product experts.

Don’t forget to search before opening a new topic!