Pagination

List endpoints use cursor (keyset) pagination — stable and efficient even as data changes under you.

Request

Param	Default	Notes
limit	20	Page size, max 100.
cursor	—	Opaque cursor from the previous page’s nextCursor. Omit for the first page.

curl "$TRILE_API/v1/customers?limit=50" -H "x-api-key: $TRILE_KEY"

Response

{
  "items": [ { "id": "cus_..." }, { "id": "cus_..." } ],
  "nextCursor": "eyJpZCI6ImN1c18..."
}

• items — this page, newest first.
• nextCursor — pass it back as cursor to get the next page. It is null on the last page.

Envelope

Like all responses, the list is wrapped: { "success": true, "data": { "items": [...], "nextCursor": ... }, "meta": {...} }. The shape above is the data.

Iterate to completion

async function* allCustomers() {
  let cursor: string | null = null;
  do {
    const url = new URL(`${API}/v1/customers`);
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);

    const res = await fetch(url, { headers: { "x-api-key": KEY } });
    const { data } = await res.json();
    yield* data.items;
    cursor = data.nextCursor;             // null ends the loop
  } while (cursor);
}

• Treat the cursor as opaque — don’t decode or construct it.
• Some endpoints accept extra filters (status, search, date ranges) alongside paging; see each operation in the API Reference.
• A handful of small sub-resource lists (e.g. an invoice’s event timeline) return a bare array rather than a paged envelope — those are noted on the endpoint.