Pagination

List endpoints accept limit and offset query parameters and return a total in the envelope so callers know when they’ve walked to the end.

Endpoints that paginate

• GET /v1/operators/search?q=…
• GET /v1/jurisdictions/:code/operators
• GET /v1/operators/:slug/licenses

Parameters

Param	Default	Max	Notes
limit	50	200 (authenticated) / 3 (unauth on /operators/search)	Negative values rejected with 400.
offset	0	—	Zero-based. High offsets have linear scan cost; prefer stable cursor if you’re walking 10k+ rows.

Response envelope

{
  "q": "...",
  "total": 1420,
  "limit": 50,
  "offset": 100,
  "operators": [ ]
}

• total — rows matching the query, ignoring limit/offset.
• operators[].length <= limit.

Walking a result set

# Bash loop — fetch all operators for UKGC.
offset=0
while :; do
  resp=$(curl -sH "Authorization: Bearer $KEY" \
    "https://api.igregulator.io/v1/jurisdictions/UKGC/operators?limit=200&offset=$offset")
  rows=$(echo "$resp" | jq '.operators | length')
  [ "$rows" -eq 0 ] && break
  echo "$resp" | jq '.operators[]'
  offset=$((offset + rows))
done

Why not cursor-based?

Offset pagination is simpler to document, easier for UIs that render page numbers, and cheap for our table sizes (~3,700 operators, ~4,500 licences). When any list crosses 100k rows we’ll add a cursor query param alongside — offset stays supported for back-compat.

Rate-limit interplay

Each paginated request is one API call against your quota. A full sweep of 3,700 UKGC operators at limit=200 is 19 calls — well within Starter’s 10k monthly quota, trivial within Pro’s 100k.