The items_page object represents a page of items. As a query, you can use it to filter data from a board. As an object type, it represents a set of items returned by the parent resolver.

Every board has advanced filters that enable you to retrieve items based on specified criteria quickly. You can replicate this behavior via the API using the items_page object and customized parameters to filter your results.

As the monday.com platform evolves, so does the allotted number of items on each board. These filters are the only way to retrieve items from larger boards without hitting any limits or timeouts, since you can't query a board with all items.

As a bonus, these filters are more expressive so you don't have to waste any of your complexity budget retrieving unnecessary data.

🚧

Want to read specific items on a board?

The items_page object allows you to query and filter all items on a board. If you want to read specific items using their IDs (up to 100 at a time), use the items object instead!

Queries

You can use the items_page query to retrieve item data via the API.

• Returns an object containing metadata about a collection of items filtered by the specified criteria
• Can't be queried at the root; must be nested within a boards or groups query

query {
  boards(ids: 1234567890) {
    items_page(
      limit: 1
      query_params: {
        rules: [
          {
            column_id: "status"
            compare_value: [1]
          }
        ]
        operator: and
      }
    ) {
      cursor
      items {
        id
        name
      }
    }
  }
}

Arguments

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

Fields

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

Cursor-based pagination using next_items_page

items_page utilizes cursor-based pagination to help return smaller sets of items from a large data set. When querying items_page, you can return the cursor argument that represents the next page of items.

After returning the cursor, you can keep paginating through the data set using the next_items_page object. This object allows you to retrieve the next page of items while avoiding the complexity cost of nesting items_page within a boards query. It takes the cursor argument, so you can specify where in the data set you want to start from.

Use cases

Let's dive into a few use cases to demonstrate how and when to use the items_page object to filter and sort items.

Filtering items by name

You only want to retrieve items named "New item" on board 1234567890.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "name"
            compare_value: ["New item"]
          }
        ]
      }
    ) {
      cursor
      items {
        id
      }
    }
  }
}

Filtering items assigned to yourself with a checkmark

You only want to retrieve items assigned to yourself with a checkmark in the checkbox column on board 1234567890.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "people"
            compare_value: ["assigned_to_me"]
            operator: any_of
          }
          {
            column_id: "check"
            compare_value: null
            operator: is_not_empty
          }
        ]
        operator: and
      }
    ) {
      cursor
      items {
        id
        name
      }
    }
  }
}

Filtering items with specific status and people column values

You only want to retrieve items assigned to Person 1 (ID#76543210) or Person 7 (ID#01234567). In addition, you just need items marked as Done or Removed in the status column on board 1234567890.

With the people column, you have two different ways to filter data:

1. Send their name(s) as a string along with the contains_text operator
2. Use the any_of operator along with their IDs as a string in the following format: "person-XXXXXXXX"

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "people"
            compare_value: ["Person 1", "Person 2"]
            operator: contains_text
          }
          {
            column_id: "status"
            compare_value: [1, 0]
          }
        ]
        operator: and
      }
    ) {
      cursor
      items {
        id
        name
      }
    }
  }
}

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "people"
            compare_value: ["person-87654321", "person-12345678"]
            operator: any_of
          }
          {
            column_id: "status"
            compare_value: [1, 0]
          }
        ]
        operator: and
      }
    ) {
      cursor
      items {
        id
        name
      }
    }
  }
}

Filtering items with specific date column values in a particular group that are not assigned to yourself

You only want to retrieve items assigned to everyone but yourself, with a release date between June 1 and June 30, 2023, also in the group named Finished on board 1234567890.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "date"
            compare_value: ["2023-06-01", "2023-06-30"]
            operator: between
          }
          {
            column_id: "group"
            compare_value: ["new_group12345"]
            operator: any_of
          }
          {
            column_id: "people"
            compare_value: ["assigned_to_me"]
            operator: not_any_of
          }
        ]
        operator: and
      }
    ) {
      cursor
      items {
        id
        name
      }
    }
  }
}

Sorting items by column type

You can also use the items_page object to sort items by column type.

Let's say you want to retrieve items from a board and sort them by the item name column. The following query will return the first 25 items on board 1234567890 in ascending order (alphabetically) within each group.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        order_by: [
          {
            column_id: "name"
          }
        ]
      }
    ) {
      cursor
      items {
        id
        name
      }
    }
  }
}