Skip to main content

Pagination

Endpoints that return lists of resources are paginated. You control pagination with two parameters:

  • page: which page to retrieve (starts at 1)
  • offset: how many items per page (minimum 1, maximum varies per endpoint)

The default offset on most endpoints is 12.

GET endpoints​

For GET requests that support pagination, pass page and offset as query parameters:

GET /v2/{resource}?page=1&offset=10

GET /v2/{resource}?page=2&offset=10

GET /v2/{resource}?page=3&offset=10

POST search endpoints​

For POST search endpoints like /v2/orders/search, include pagination in the request body alongside your filters:

{
  "status": ["NEW"],
  "page": 1,
  "offset": 25
}

Response metadata​

Most list endpoints, such as the order search, return the resources of the current page in an items array, with the metadata alongside it:

{
  "items": [
    { "id": 20106, "status": "NEW" },
    { "id": 20105, "status": "NEW" }
  ],
  "itemsFound": 35,
  "offset": 2,
  "page": 1,
  "pages": 18,
  "start": 1,
  "end": 2
}

The searches for products, clusters, categories, product-category relationships, companies, contacts, customers and inventory return the resources in a data array instead, and add messages and total:

{
  "data": [
    { "id": 56897, "sku": "QSFP-40G-SR4" },
    { "id": 36975, "sku": "C9600-LC-48YL" }
  ],
  "messages": ["Search completed successfully"],
  "start": 1,
  "end": 2,
  "page": 1,
  "pages": 18,
  "total": 35,
  "offset": 2,
  "itemsFound": 35
}
FieldTypeDescription
items or dataarrayArray of resources for the current page
startintegerFirst item number on the current page
endintegerLast item number on the current page
pageintegerCurrent page number
pagesintegerTotal number of pages
offsetintegerNumber of items per page
itemsFoundintegerTotal number of items across all pages
totalintegerdata form only: total number of items across all pages
messagesarraydata form only: messages about the request

On the category search and the product-category relationship search, itemsFound is the number of items on the current page. Use total there for the number of items across all pages.

To iterate through all results, loop from page 1 to pages, incrementing by 1.

See also​