Pagination

Phosra returns lists in two shapes, and which one you get depends on the surface — not on a query flag. Read this once and you will never wonder whether a response has "more".

Runnable. The shapes below were captured live from https://phosra-api-sandbox-production.up.railway.app on 2026-07-06. The catalog reads (/api/v1/platforms, /api/v1/ratings/systems) need no API key.

The two shapes at a glance

Surface	Shape	Page with	`next` signal	Example
Product data plane (families, devices, enforce history, webhook deliveries, viewing history)	a bare JSON array	`?limit=` and `?offset=`	array shorter than `limit` ⇒ last page	`GET /api/v1/enforce/history?limit=20&offset=40`
OCSS census rails (advisor audit log, CSM bulk ratings)	an envelope `{ "<items>": [...], "next_cursor": … }`	`cursor` in the body/query	`next_cursor` is `null` ⇒ last page	`POST /api/v1/csm/reviews/bulk`
Static catalogs (platforms, ratings systems, standards)	a bare JSON array, complete	(not paginated)	full set every time	`GET /api/v1/platforms`

There is no has_more, no total_count, and no "object": "list" wrapper. Product lists are bare arrays; census lists carry next_cursor. Do not code against fields Phosra does not return — detect the last page by the two rules in the table above.

Offset lists (product data plane)

Most product list endpoints return a plain array and accept limit and, where supported, offset. An empty result is [], never null.

bash

BASE=https://phosra-api-sandbox-production.up.railway.app
curl -s -H "Authorization: Bearer $PHOSRA_API_KEY" \
  "$BASE/api/v1/enforce/history?limit=20&offset=0"

json

[
  { "id": "b1f0…", "status": "completed", "created_at": "2026-07-05T18:20:10Z" },
  { "id": "a7c2…", "status": "completed", "created_at": "2026-07-05T18:19:55Z" }
]

Limits and defaults

Each endpoint sets its own default and ceiling. Ask for more than the ceiling and you get the ceiling.

Endpoint	`limit` default	`limit` max	`offset`
`GET /api/v1/enforce/history`	`20`	`100`	✅
`GET /api/v1/webhooks/{id}/deliveries`	`50`	—	—
`GET /api/v1/viewing-history/{childId}`	repo default	—	✅

Walk every page

Keep advancing offset by limit until you get back fewer rows than you asked for — that short page is the last one.

typescript
async function* allEnforceJobs(base: string, key: string, pageSize = 100) {
  let offset = 0;
  for (;;) {
    const res = await fetch(
      `${base}/api/v1/enforce/history?limit=${pageSize}&offset=${offset}`,
      { headers: { Authorization: `Bearer ${key}` } },
    );
    const page: unknown[] = await res.json();
    yield* page;
    if (page.length < pageSize) return; // short page ⇒ done
    offset += pageSize;
  }
}

Offset lists are newest-first and mutable. New rows land at offset 0, so a row can shift while you page. For an audit-stable walk, filter by a fixed created_at/since window rather than relying on offsets across a long crawl.

Cursor lists (OCSS census rails)

The OCSS census rails return an envelope with the collection plus a next_cursor. The cursor is opaque — treat it as a token, never parse it — and null means you have reached the end. Pass it back verbatim to get the next page.

json

{
  "consultations": [
    { "advisor_id": "did:ocss:…", "capability": "age_estimate", "at": "2026-07-05T…" }
  ],
  "next_cursor": null
}

For the CSM bulk rail the cursor rides the request body (it is part of the signed, convergent payload — the same request set and cursor always return the same records):

json

{ "slugs": ["bluey", "paw-patrol", "…"], "cursor": "", "idempotency_key": "…" }

typescript

// Cursor loop: pass next_cursor back until it comes back null.
async function* csmBulk(base: string, sign: SignFn, slugs: string[]) {
  let cursor = "";
  for (;;) {
    const body = JSON.stringify({ slugs, cursor });
    const res = await fetch(`${base}/api/v1/csm/reviews/bulk`, {
      method: "POST",
      headers: sign("POST", `${base}/api/v1/csm/reviews/bulk`, body),
      body,
    });
    const { reviews, next_cursor } = await res.json();
    yield* reviews;
    if (next_cursor == null) return; // null ⇒ done
    cursor = next_cursor;
  }
}

Never construct or mutate a cursor. next_cursor is a server token. Send it back byte-for-byte; do not decode it, add to it, or assume it is a row id — its encoding is not part of the contract and can change.

Choosing a page size

Bigger pages, fewer calls

Each request counts against your rate limit. Pull 100 at a time on offset lists rather than 10 at a time.

Detect the end correctly

Offset lists: a short page ends the walk. Cursor lists: a null next_cursor ends the walk. Never guess with a count you were not given.

Pagination

The two shapes at a glance

Offset lists (product data plane)

Limits and defaults

Walk every page

Cursor lists (OCSS census rails)

Choosing a page size

Bigger pages, fewer calls

Detect the end correctly

Next steps

Limits & quotas

Rate limits

Idempotency