Pagination
How to paginate through list endpoints using cursor-based pagination.
List endpoints return results in pages using cursor-based pagination. This ensures consistent results even when new items are added between requests.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 50 | Items per page (1–100) |
starting_after | string | — | Cursor: the id or number of the last item from the previous page |
Response format
Every list response includes pagination metadata:
{
"object": "list",
"data": [...],
"has_more": true,
"total_count": 25
}| Field | Description |
|---|---|
has_more | true if there are more results after this page |
total_count | Number of items in the current page |
Paginating through results
To get all results, keep requesting pages until has_more is false:
let allEvents = [];
let cursor: string | undefined;
do {
const params = new URLSearchParams({ limit: "100" });
if (cursor) params.set("starting_after", cursor);
const res = await fetch(
`https://api.lucius.finance/v1/billing/usage?${params}`,
{ headers: { Authorization: "Bearer luc_live_YOUR_KEY" } },
);
const page = await res.json();
allEvents.push(...page.data);
cursor = page.has_more ? page.data[page.data.length - 1].id : undefined;
} while (cursor);Cursor values by endpoint
| Endpoint | Cursor field |
|---|---|
GET /v1/billing/usage | id (event idempotency key) |
GET /v1/billing/invoices | number (invoice number) |
The contracts endpoint currently returns all contracts in a single response without pagination.