API Reference Pagination v2
API endpoints that can return large numbers of objects return their results using an offset-based paging mechanism to improve performance. Applications can specify limit
and offset
query parameters to control what subset of the results are returned to them.
- The
limit
parameter sets a maximum number of results to return per call. - The
limit
parameter defaults to a value of 25 - The
limit
parameter has a maximum value of 200 - The
offset
parameter defines the number of resources in the collection to skip before assembling the results array - The
offset
parameter defaults to 0
To fetch the first set of entries, call the endpoint with offset = 0
and limit = <your-limit>
. To fetch the next set of entries, call the endpoint with offset = <previous-offset> + <previous-limit>
. Note that you should increment the offset by the limit that is returned in the response object, not by the limit you passed in the query parameter or size of the results array. If <previous-offset> + <previous-limit> >= total
, then you have retrieved all of the entries and there are no more to fetch. Note that the total may change between API calls, so always use the most recent values.
A sample request
For an application displaying an organization’s workspaces 10 records at a time, the query for page 2 would look like:
/v2/organizations/OPki5yp3-7UQaGtC91gE/workspaces?offset=10&limit=10
Endpoints that support paging return the requested data as well as additional information related to paging:
- the set of results
- the
offset
specified in the query - the
limit
specified in the query - the
size
of the result set returned by the query - the
total
number of resources available in the collection - a
paging
object containing prepared queries for your convenience:- the
self
URL reflects the request that generated this response - the
next
URL can be used to request the next page of results - the
prev
URL can be used to request the previous page of results
- the
A sample response
{
"workspaces": [ // the results array
{
"uid": "4Nkidyp3CpUQaotRx1gE",
"name": "Workspace 1",
...
},
{
"uid": "EUYYqLMUzLp5vww_z-mf",
"name": "Workspace 2",
...
},
...
],
"limit": 10, // the query requested a maximum of 10 results
"offset": 10, // the query requested to skip the first 10 workspaces (page 1)
"size": 10, // the number of results returned for this query
"total": 50, // the number of workspaces available in the organization
"paging": {
// request URL for the previous page
"prev": "/v2/organizations/OPki5yp3-7UQaGtC91gE/workspaces?offset=0&limit=10",
// request URL for the current page
"self": "/v2/organizations/OPki5yp3-7UQaGtC91gE/workspaces?offset=10&limit=10",
// request URL for the next page
"next": "/v2/organizations/OPki5yp3-7UQaGtC91gE/workspaces?offset=20&limit=10",
}
}
Where to Next?
Not what you were looking for? Reply below or Search the community and discover more Bluescape.