Skip to content
Arbitex Docs

Pagination

The Gateway API’s read-back endpoints return results a page at a time. There is no single pagination style across them — each endpoint uses the scheme that fits its data, and the parameters and envelope fields differ accordingly. This guide covers all three so you can iterate any list endpoint to exhaustion without skipping or double-counting rows.

Whichever scheme an endpoint uses, one rule holds: let the response tell you when to stop. Don’t guess the total from the page size — read the terminal signal each envelope gives you.

Cursor pagination — audit events

Section titled “Cursor pagination — audit events”

Audit events (GET /v1/audit/events) uses cursor-based pagination. Cursors are stable under concurrent writes: because new events are always appended, the cursor pins your position in the stream and you never skip or re-read a row while the log grows underneath you.

The response envelope is { "events": [...], "next_cursor": ..., "has_more": ... }:

Terminal window
# First page
curl -s "https://api.arbitex.ai/v1/audit/events?limit=100" \
  -H "Authorization: Bearer arb_live_your-api-key-here"


# Next page — pass next_cursor from the previous response back as cursor
curl -s "https://api.arbitex.ai/v1/audit/events?limit=100&cursor=<next_cursor>" \
  -H "Authorization: Bearer arb_live_your-api-key-here"
  • limit sets the page size (1–500, default 50).
  • cursor is opaque — do not parse, construct, or modify it. Pass back exactly what you received in next_cursor.
  • Stop when has_more is false (next_cursor is then null). That is the only reliable end-of-data signal.

Page pagination — DLP events

Section titled “Page pagination — DLP events”

DLP results (GET /api/v1/dlp/events) uses page-number pagination — a good fit for a bounded, filterable event set you may want to jump around in.

The response envelope is { "items": [...], "total": ..., "page": ..., "page_size": ... }:

Terminal window
curl -s "https://api.arbitex.ai/api/v1/dlp/events?page=1&page_size=100" \
  -H "Authorization: Bearer arb_live_your-api-key-here"
  • page is 1-based (default 1); page_size is 1–200 (default 50).
  • total is the count of matching events across all pages. You have read everything once page * page_size >= total.
  • Increment page until you have collected total items.

Offset pagination — usage records

Section titled “Offset pagination — usage records”

Usage & cost (GET /api/v1/usage/records) uses offset pagination.

The response envelope is { "records": [...], "total": ..., "limit": ..., "offset": ... }:

Terminal window
curl -s "https://api.arbitex.ai/api/v1/usage/records?limit=100&offset=0" \
  -H "Authorization: Bearer arb_live_your-api-key-here"
  • limit is the page size (1–200, default 100); offset is the number of records to skip (≥ 0, default 0).
  • To advance, set offset = offset + limit. You have retrieved everything once offset + limit >= total.

Guidance

Section titled “Guidance”
  • Read the terminal signal, not the page length. A full-sized page does not mean there is another page, and a short page does not always mean you are done — trust has_more / total.
  • Keep the page size reasonable. Smaller pages mean more round-trips; larger pages mean heavier responses. Stay within each endpoint’s documented maximum.
  • Filters compose with pagination. Any filter you apply (by action, entity type, date range, and so on) narrows total and the pages you walk — apply the filter once and paginate the filtered result.

Next steps

Section titled “Next steps”