Cursor
In REST and HTTP APIs, a cursor helps you page through a large result set when the server cannot return every row at once. The server returns a batch of rows (for example, up to 100) plus a string value that tells the server where to continue in the sorted results on the next request.
When the response is paginated, the Cursor object often includes:
Self— cursor value for the current page (the batch you just received).Next— cursor value for the following page. On the last page, this is empty or omitted because there is nothing left to fetch.
For example, if there are 300 records and the maximum page size is 100, the first response returns rows 1–100 and includes a Cursors object with Next and Self. Call the endpoint again with the cursor set to the Next value from the previous response to retrieve the next page of results (for example, rows 101-200). Continue this process until the API stops returning a Next value, indicating there are no more results to fetch.
Many responses also include a Links object with ready-to-request URLs for the same pages. For more details, see
Links.
Example
A paginated response often includes Data, Links, and Cursors:
{
"Data": [ ... ],
"Cursors": {
"Next": "qKLVZ/HGD2XeFkiwNFWJK+nRDuOjjBRipct8qOfRjRmGUG8F5P1WzrQ4p3JFfXoErs96xb+DS0SAPW+XDUi9Zw/zdo4uHXL3TYBhodxfQQul3L4mwDk=",
"Self": "KYhsR26Se8cQbeQm+o3LXawJXu3Pe6NvSefBcMivZ5QA+rFcRUrHTErK+TrhrUN3Ss8QUing/+jUkjgl3QOvB3kf3AZ+EOubhya5s3CWF+HGWEQkQQ=="
},
"Links": {
...
},
}
You can start with the most recent data and move backward in time (Sorting=Descending), or start at the beginning of a time range and move toward the present (Sorting=Ascending).
Sorting=Ascending is useful when an automated process polls for new data. For example, you might call the API every five minutes with PresetPeriod=Last24Hours, Sorting=Ascending, and the cursor value from the previous response. The API then returns rows produced since your last request. The Data array may be empty if no new rows are available yet. You can use the cursor from the response on the next call to continue.