Pagination

Page through any list with limit, starting_after and has_more; filter by created date.

Embed
Preview of the card
<a href="https://referalli.com/docs/pagination"><img src="https://referalli.com/docs/_api/public/orgs/07f432f4-34b9-46a7-aaad-c0e395d2e4f9/spaces/2bf4f614-3630-4fbf-85f9-5ecafa6b7d97/pages/4c45f1d4-b09a-4931-bd11-1564c4c4ea80/social-card.svg?v=3e7ae33eec8b" alt="Pagination" width="600" height="315"></a>

From referally-version: 2026-11-01, every list endpoint pages the same way. (Under 2026-10-21, lists return a plain array with a per-endpoint cap; see Versioning.)

{
  "object": "list",
  "data": [{ "id": "ref_01JB...", "...": "..." }],
  "has_more": true,
  "next_cursor": "ref_01JB..."
}

Parameter

Meaning

limit

Items per page, 1 to 100. Default 50.

starting_after

An item id (usually next_cursor from the previous page): returns the items after it.

ending_before

An item id: returns the page before it, still in list order.

created[gte], created[lte]

ISO 8601 dates. Keep items created (or, for events, recorded) in that range.

Lists are ordered newest first, with the id as a tiebreak, and paging uses the cursor's position rather than an offset. Items added while you page never shift a page or repeat one. An id that isn't in the list returns 404; sending both starting_after and ending_before returns 400.

Filters an endpoint already takes (status, partnerId, programId and so on) combine with paging.

Walk a whole list

cursor=""
while :; do
  page=$(curl -s "https://referalli.com/v1/referrals?limit=100${cursor:+&starting_after=$cursor}" \
    -H "Authorization: Bearer $KEY" -H "referally-version: 2026-11-01")
  echo "$page" | jq -c '.data[]'
  [ "$(echo "$page" | jq -r .has_more)" = "true" ] || break
  cursor=$(echo "$page" | jq -r .next_cursor)
done

With @referally/sdk-js, list() does the same:

for await (const referral of client.list('/v1/referrals', { status: 'active' })) {
  // every referral, a page at a time
}

client.listPage(path, { limit, starting_after }) returns one page when you want to control the paging yourself.

Updated