Comment on page
Pagination
API Reference - pagination and listing
Most API resources have list API methods. For instance, you can list projects, list runs for a project.
Those methods utilize cursor-based pagination via the
starting_after
and ending_before
parameters. Both parameters take an existing pointer value (see below) and return objects in a particular order. These list API methods share a common structure, taking optional parameters:
limit
, starting_after
, and ending_before
.Please note: Listing parameters are mutually exclusive -- only one of
starting_after
or ending_before
may be used.Parameter | Description |
---|---|
limit | Limit the number of returned items. Valid values are 1 to 50. The default value is 10. |
starting_after | Pagination cursor - if specified, the response will list items created before the pointed item. |
ending_before | Pagination cursor - if specified, the response will list items created after the pointed item on reverse chronological order |
All "list" API method responses have the
has_more
flag, every item of the requested type has a cursor
field that can be used for pagination, for example:// GET https://api.currents.dev/v1/projects/bAYZ41/runs
{
"status": "OK",
"has_more": true,
"data": [
{
"runId": "9ee42e4b85c02c634fe30b26d728624e",
"cursor": "62c538efcbd7fab8a5edb371",
// ...
}, {
"runId": "9af7a261f148d1b45d013eec6a22902e",
"cursor": "62baacbf9f4689a83d2b24cb",
// ...
},
// ...
]
}
If
has_more
value is true, you can get additional items from the "list" API, using cursor-based pagination.Currents' list API methods utilize cursor-based pagination via the
starting_after
and ending_before
parameters. Both parameters take an existing pointer value (see below) and return objects in a particular order. - if
ending_before
specified - in reverse chronological order - if
starting_after
is specified - in chronological order - if none specified - in chronological order
The
ending_before
parameter returns items created before the pointed item. The starting_after
parameter returns items listed after the pointed item. For example, given a chronologically ordered list of items in a DB and using
pointer1003
as a reference:pointer1006
pointer1005
pointer1004
pointer1003 <
pointer1002
pointer1001
pointer1000
starting_after=pointer1003
would return
pointer1002
pointer1001
pointer1000
ending_before=pointer1003
would return (in reverse chronological order)
pointer1004
pointer1005
pointer1006
Some API resources don't have a stable cursor, for example - listing spec files for a project is an aggregative query that doesn't have a corresponding stable database entity. We use offset-based pagination for those resources. The resources using offset pagination have an explicit notice.
The responses for such resources have the following shape:
{
"status": "OK",
"data": {
// ... resource-specific data
"nextPage": number | false,
"total": number
}
}
total
field contains the total number of items retrieved by the querynextPage
field contains the next page to be used for retrieving additional items. If the value isfalse
it means all the items were exhausted and no more pages are available.
To retrieve more items from a paginated response, use the following query parameters:
Parameter | Description |
---|---|
limit | Limit the number of returned items. Valid values are 1 to 50. |
page | Pagination cursor - if specified, the response will return items from the spec files list based on a splice operation. |
The offset will be calculated as follows:
items.splice(page * limit, limit)
Last modified 1mo ago