In the 2023-10 API release, we introduced the items_page object which utilizes cursor-based pagination to retrieve smaller groups of items from a large data set. This object must be nested inside of a boards query, so it has a high complexity cost.
To help reduce that cost, we created the next_items_page object which can be used at the root of your query to paginate through the data set. It takes both the cursor and limit arguments and retrieves the following page of items in the data set.
Now let’s break it down a bit…
Say you only want to retrieve items with a blank status column from board 1234567890. This board contains thousands of items that cannot be retrieved simultaneously, so you can use cursor-based pagination.
The query below would return the ID and name of the first 50 items with a blank status column and a cursor value that represents the position in the data set after returning 50 items.
query {
boards (ids:1234567890) {
items_page (limit: 50, query_params: {rules: {column_id: "status", compare_value: [5], operator:any_of}}) {
cursor
items {
id
name
}
}
}
}
You can then use the next_items_page object with the cursor argument from the first query to return the following 50 relevant items in the data set. After returning the next cursor value, you can continue paginating through the entire data set.
query {
next_items_page (limit: 50, cursor: "MSw5NzI4MDA5MDAsaV9YcmxJb0p1VEdYc1VWeGlxeF9kLDg4MiwzNXw0MTQ1NzU1MTE5") {
cursor
items {
id
name
}
}
}