Pagination
List endpoints return collections in pages. Currents uses cursor-based and offset-based pagination for various API endpoints. This page describes both patterns.
Cursor-based pagination
Use cursor pagination for list methods such as listing projects or runs for a project.
Parameters
Optional query parameters:
limit
Maximum number of items in this page. 1–50, default 10.
starting_after
Cursor from a previous item. Returns the next page of items older than that item (see Sort order).
ending_before
Cursor from a previous item. Returns the next page of items newer than that item (see Sort order).
Only one of starting_after or ending_before may be sent in a single request. They are mutually exclusive.
Response shape
Every list response includes has_more. Each item in data includes a cursor string you pass back as starting_after or ending_before on the next request.
Example: GET https://api.currents.dev/v1/projects/bAYZ41/runs
{
"status": "OK",
"has_more": true,
"data": [
{
"runId": "9ee42e4b85c02c634fe30b26d728624e",
"cursor": "62c538efcbd7fab8a5edb371"
},
{
"runId": "9af7a261f148d1b45d013eec6a22902e",
"cursor": "62baacbf9f4689a83d2b24cb"
}
]
}When has_more is true, request the next page using the appropriate cursor parameter (see below).
Sort order
Picture the full timeline as newest at the top, oldest at the bottom (like a “latest first” feed):
Neither starting_after nor ending_before
First page, in that endpoint’s default order.
starting_after=cursor_B
Items older than B (e.g. cursor_A, …)—continuing down toward the oldest. The API describes this page as chronological order.
ending_before=cursor_B
Items newer than B (e.g. cursor_C, cursor_D, …)—continuing up toward the newest. The API describes this page as reverse chronological order.
Example: next page (older items)
After the first request, take the last item’s cursor in data and call again with starting_after:
Stop when has_more is false or data is empty.
Example: page toward newer items
Use ending_before with a cursor from an item newer than the slice you want to extend (often the first item of the current page when walking back toward the present):
Offset-based pagination
Some list operations (for example, aggregated lists such as spec files for a project) do not map to a stable row cursor. Those endpoints document offset pagination explicitly.
Response shape
total
Total number of items matching the query (across all pages).
nextPage
Page index to request next, or false when there are no more pages.
Parameters
limit
Page size. 1–50.
page
Zero-based page index.
The slice applied server-side is:
(Equivalent to items.splice(page * limit, limit) for a copy of the list.)
Example
First page:
If data.nextPage is 1, fetch the next page with page=1, same limit, until nextPage is false.
Last updated
Was this helpful?