Pagination
Page through large outbound responses with Size and Cursor, and read the Paging block.
Outbound endpoints return their results one page at a time. Use this page to control the page size and to fetch every page of a result.
How it works
Each GET that returns a list accepts two query parameters:
| Parameter | Meaning |
|---|---|
Size | The number of records per page. See the API Reference for the range and default. |
Cursor | Where the page starts. Omit it for the first page; afterwards pass the NextCursor from the previous response. |
The response holds the records in Data and the paging details in Paging:
| Field | Meaning |
|---|---|
Paging.NextCursor | The cursor for the next page, or null on the last page. |
Paging.CurrentDataCount | The number of records in Data on this page. |
Fetch every page
Request the first page without a Cursor:
GET /api/v1/locations?Size=2 HTTP/1.1
Host: acme.gainsystems.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqTl9F...{
"DataType": "location",
"Data": [
{
"LocationCode": "CHI01",
"Name": "Chicago DC",
"Type": "DC",
"ParentDefaultCode": null,
"Address1": "2200 W Lake St",
"Address2": null,
"City": "Chicago",
"State": "IL",
"Country": "US",
"PostalCode": "60612",
"Latitude": 41.8847,
"Longitude": -87.6808,
"StartDate": "2024-01-01",
"EndDate": null,
"Size": "LARGE",
"CurrencyCode": "USD"
},
{
"LocationCode": "DAL02",
"Name": "Dallas DC",
"Type": "DC",
"ParentDefaultCode": "CHI01",
"Address1": "1500 Market Center Blvd",
"Address2": null,
"City": "Dallas",
"State": "TX",
"Country": "US",
"PostalCode": "75207",
"Latitude": 32.7957,
"Longitude": -96.8217,
"StartDate": "2025-03-15",
"EndDate": null,
"Size": "MEDIUM",
"CurrencyCode": "USD"
}
],
"Paging": {
"NextCursor": "k3Jf9QzX2mPa7LwT0bYc4g==",
"CurrentDataCount": 2
}
}Then pass NextCursor as Cursor, with the same filters, and repeat until NextCursor is null:
GET /api/v1/locations?Size=2&Cursor=k3Jf9QzX2mPa7LwT0bYc4g%3D%3D HTTP/1.1
Host: acme.gainsystems.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqTl9F...Rules
- Treat
NextCursoras opaque. Pass it back exactly as received, URL-encoded like any query value; it can end in=. - Keep the same filters on every page. A cursor marks a position in one result; combining it with different filters gives an undefined result.
- The last page can be full. Stop when
NextCursorisnull, not when a page holds fewer thanSizerecords. - A cursor does not expire, but data that changes in GAINS while you page can appear on a later page or be missed.
What a record is
Size counts the units an endpoint returns:
| Endpoints | One record is |
|---|---|
| Purchase, transfer, work and production orders | An order, with all its lines |
| Forecasts, inventory policies, service levels, bills of material, lead-time predictions | A SKU-location |
| Supercessions | A replaced SKU-location: one entry in OldItems |
| All other list endpoints | One entry in Data |
Where records are grouped under an item, a page can hold fewer entries in Data than Size, and the same item can continue on the next page. The subject pages below explain how to merge them.
Errors
| Status | Reason | Cause |
|---|---|---|
400 | The page size parameter specified is not valid | Size is not a whole number in the accepted range. |
400 | Wrong cursor value | Cursor was altered, truncated or not URL-encoded. |
See Errors & Retries for the error body.
Related
Updated 9 days ago