Skip to main content

Pagination

Adjudon's list endpoints use one of two pagination schemes — page-based for most resources and cursor-based for streaming or append-only resources. The form applied to each list endpoint is documented inline on the per-resource page; this page is the shared reference. Tested against API version v1.

Two schemes, one ordering rule​

Most-recent-first is the default ordering on every list endpoint. Time-keyed resources (DecisionTrace, AuditLog, notifications, incidents) sort by createdAt or timestamp descending. Sequence-keyed resources (HashChainEntry) sort by sequence descending. The ordering is stable: equal-time entries break ties by _id.

Page-based (the default)​

Used on traces, audit, fria, incidents, webhooks, auto-approval, notifications, and most other list endpoints.

Query parameterDefaultDescription
page11-indexed page number
limitvaries (25 or 50)Page size; capped server-side at the per-endpoint maximum

Per-endpoint limit caps appear in the resource page's parameter table. Common ceilings: 200 for traces, 500 for audit and hash-chain entries.

curl — page 1, 25 per page
curl "https://api.adjudon.com/api/v1/traces?page=1&limit=25" \
  -H "Authorization: Bearer $ADJUDON_API_KEY"
Python — walk pages until exhausted
import os, requests
def walk_traces():
    page = 1
    while True:
        r = requests.get(
            "https://api.adjudon.com/api/v1/traces",
            params={"page": page, "limit": 50},
            headers={"Authorization": f"Bearer {os.environ['ADJUDON_API_KEY']}"},
        )
        body = r.json()
        for trace in body["data"]:
            yield trace
        if not body["pagination"]["hasMore"]:
            break
        page += 1

Response (200 OK):

{
  "success": true,
  "data": [/* resource-shaped */],
  "pagination": { "page": 1, "limit": 25, "total": 1247, "pages": 50, "hasMore": true }
}

hasMore is the canonical signal that more rows are available. Prefer hasMore over computing page < pages — the boolean already accounts for the edge cases.

Cursor-based (streaming / append-only)​

Used on hash-chain/entries and org/sso/activity — resources where new rows append continuously and a numeric page would fragment under live writes.

Query parameterDescription
limitPage size; capped per endpoint (500 on hash-chain/entries)
beforeSeq (hash-chain)Cursor: returns rows with sequence < beforeSeq
cursor (sso-activity)Opaque cursor token returned in nextCursor
curl — first page
curl "https://api.adjudon.com/api/v1/hash-chain/entries?limit=100" \
  -H "Authorization: Bearer $ADJUDON_API_KEY"
Python — walk via cursor
last_seq = None
while True:
    params = {"limit": 100}
    if last_seq:
        params["beforeSeq"] = last_seq
    r = requests.get(
        "https://api.adjudon.com/api/v1/hash-chain/entries",
        params=params,
        headers={"Authorization": f"Bearer {os.environ['ADJUDON_API_KEY']}"},
    )
    body = r.json()["data"]
    for entry in body["entries"]:
        yield entry
    if not body["hasMore"]:
        break
    last_seq = body["entries"][-1]["sequence"]

Response (200 OK):

{
  "success": true,
  "data": {
    "entries": [/* HashChainEntry[] */],
    "hasMore": true
  }
}

Cursor-based endpoints do not return total — computing the total under live appends is expensive and stale by the time the client reads it.

Stability and freshness​

A list response is a snapshot of state at the moment the query ran. On a high-write resource, paging deeply through a result set may encounter rows that were inserted between page reads. Page-based schemes can drift under live writes (the same row can appear on two pages, or be skipped). Cursor-based schemes on append-only resources are stable by construction.

If you need a consistent snapshot of a high-write resource, use the date-bounded export endpoint (e.g., /api/v1/hash-chain/export?from=…&to=… for the chain) instead of walking the list.

See also​