Pagination

List queries in Propeller's GraphQL API return results one page at a time. Products, orders, carts, categories and other collection queries share the same paging inputs and response fields, so once you know the pattern it applies everywhere.

Page size and page number

Two inputs control paging:

• offset sets the page size: the number of items returned per page. It defaults to 12.
• page sets which page to return, counting from 1. It defaults to 1.

The two combine to select a slice of the full result set. With offset: 24 and page: 2, the response holds items 25 through 48.

query Products($page: Int, $offset: Int) {
  products(input: { page: $page, offset: $offset }) {
    items {
      ... on Product {
        productId
      }
    }
    itemsFound
    page
    pages
    start
    end
  }
}

{
  "page": 2,
  "offset": 24
}

Response fields

Every paginated response returns the same fields alongside items:

Field	Description
itemsFound	Total number of items matching the query, across all pages
page	The page that was returned
pages	Total number of pages available
start	Position of the first item on this page within the full result set
end	Position of the last item on this page

Select itemsFound and pages whenever the total matters. They tell you how many results exist beyond the current page and how many pages you need to read to cover them all.

Reading every match

Because the default page size is 12, a query that does not set offset returns the first 12 matches. When a collection can hold more than that, read itemsFound and pages from the first response, then request the remaining pages:

1. Run the query with page: 1 and the page size you want.
2. Read pages from the response.
3. Request page: 2 through the last page, collecting items from each.

For a set you know is small, a single request with a larger offset is simpler. Keep the page size sensible: very large pages are slower to resolve and heavier to transfer than reading a few pages of a moderate size.

Building pagination controls

For a paged interface, itemsFound, page and pages give a pager everything it needs: the total count for a results summary, the current position and the number of page links to render. start and end map directly to a "showing 25 to 48 of 236" label.

Where this applies

The same inputs and response fields appear on list queries throughout the API, including:

• products and category listings, covered in Querying products
• orders, covered in Order history
• carts, covered in Cart management

Each guide documents the filters and fields specific to that query. The paging behavior is the same in every case.