The response body of an API endpoint may contain more results than can be returned in a single response. When this occurs, data is divided into smaller chunks and returned in a series of “pages.” This process of programmatically requesting and traversing all pages in order to retrieve the entire result data set is referred to as pagination.
Speed platform API employs cursor-based pagination to improve performance when accessing potentially large collections of objects. Although not all endpoints support or require pagination, it is frequently used when result sets are large. For instance, checkout link and payment link endpoints support pagination in the Speed platform API. These endpoints provide a directional option for navigating through results, using parameters like limit, starting_after, and ending_before.
The response of these list API methods is a single page in reverse chronological order of objects. If you do not specify starting_after or ending_before, you will receive the first page containing the latest objects. Starting_after and ending_before both use the ID of an existing object to return the data requested in the order. The ending_before parameter retrieves objects created before the object with the ID value, whereas the starting_after parameter retrieves objects created after. Objects on a page always appear in reverse chronological order. These parameters are mutually exclusive—only one of them can be used.
Parameters
limit optional, default is 10
A limit specifies the number of objects to be returned. The default page size has 10 objects per page, and it is consistent across endpoints.
starting_after optional
This parameter makes use of the object ID to determine the cursor's position in the list. For instance, if you use the starting_after param along with the ID of an object received in the response, it will fetch all the objects created after this object in the subsequent call.
ending_before optional
This parameter makes use of the object ID to determine the cursor's position in the list. For instance, if you use the ending_before param along with the ID of an object received in the response, it will fetch all the objects created before this object in the subsequent call.
When the response is truncated (there are more resources to retrieve), it returns a true value for the has_more field(see below).
{
"object": "list",
"has_more": true,
"data": [
{
"created": 1654681196048,
"modified": null,
"id": "sn_l45egm4w1x0rmSze",
"geo_country": null,
"geo_state": null,
"geo_country_code": null,
"geo_city": null,
"geo_postal": null,
"geo_latitude": null,
"geo_longitude": null,
"ip_address": "[\"103.161.98.6\"]",
"session_state": "ACTIVE",
"user_agent": "PostmanRuntime/7.29.0",
"object": "session"
},
{...},
{...}
]
}
Consider the following: your checkout link result set contains 100 link objects, but the page returned with the response contains only 10 of the latest created objects in the data array. In this case, the response includes a boolean has_more field with a true value. To retrieve another page of data, you can use the ending_before param along with the ID of the last object received in the response. You may continue to send requests as long as each call returns a response with a true value for has_more field. The last page of the result will have a false value for the has_more field.
See the API reference for more details on how to construct these requests.