Pagination

Collections that can grow without bound are cursor-paginated. A page looks like this:

{
  "items": [ … ],
  "nextCursor": "eyJzIjoic3RhcnRzQXQiLCJ2Ijoi…"
}

To get the next page, repeat the request with the same filters and sort and cursor set to the previous page’s nextCursor. When nextCursor is null, you have the last page.

• Cursors are opaque. Don’t build or edit them; their format can change.
• A cursor belongs to the query that produced it. Sending it with a different sort or different filters answers 400.
• Cursors don’t expire, so you can store one and resume a long walk later. Items inserted before the cursor’s position after you got it won’t appear; the walk is a consistent order, not a snapshot.
• limit sets the page size. Values outside the endpoint’s range answer 400.

Follow a cursor

curl

samples/curl/pagination.sh

#!/usr/bin/env bash
# Every upcoming event, 200 per page: follow nextCursor until it is null.
set -euo pipefail
API="${STATUS302_API_URL:-https://api.status302.com}"

cursor=""
total=0
while :; do
  page=$(curl --fail-with-body -sS -G "$API/v1/events" \
    -H "Authorization: Bearer $STATUS302_API_KEY" \
    --data-urlencode "limit=200" \
    ${cursor:+--data-urlencode "cursor=$cursor"})
  total=$((total + $(jq '.items | length' <<<"$page")))
  cursor=$(jq -r '.nextCursor // empty' <<<"$page")
  [ -z "$cursor" ] && break
done
echo "$total events"

TypeScript

samples/typescript/pagination.ts

// Every upcoming event, 200 per page. `paginate` follows nextCursor for you;
// `pages` yields whole pages when you want to checkpoint the cursor.
import { Status302 } from "@status302/sdk";

const status302 = new Status302({ apiKey: process.env.STATUS302_API_KEY, baseUrl: process.env.STATUS302_API_URL });

let total = 0;
for await (const event of status302.paginate("/v1/events", { query: { limit: 200 } })) {
  total += 1;
  if (total <= 3) console.log(event.id, event.name);
}
console.log(`${total} events`);

for await (const page of status302.pages("/v1/events", { query: { limit: 200 } })) {
  console.log(`page of ${page.items.length}, next cursor: ${page.nextCursor ?? "none (last page)"}`);
}

Python

samples/python/pagination.py

# Every upcoming event, 200 per page. `paginate` follows nextCursor for you;
# `pages` yields whole pages when you want to checkpoint the cursor.
import os

from status302 import Status302

with Status302(os.environ["STATUS302_API_KEY"], base_url=os.environ.get("STATUS302_API_URL", "https://api.status302.com")) as status302:
    total = 0
    for event in status302.paginate(status302.list_events, limit=200):
        total += 1
        if total <= 3:
            print(event["id"], event["name"])
    print(f"{total} events")

    for page in status302.pages(status302.list_events, limit=200):
        print(f"page of {len(page['items'])}, next cursor: {page['nextCursor'] or 'none (last page)'}")

The SDKs offer two helpers: paginate yields every item and fetches pages as you go, pages yields whole pages so you can checkpoint nextCursor between them.

Paginated endpoints

Endpoint	limit (default, max)	Order
GET /v1/events	50, 200	By sort (default: start time, soonest first)
GET /v1/events/{id}/inventory/changes	50, 200	Newest first
GET /v1/events/{id}/sales	50, 200	Newest first
GET /v1/sales/feed	50, 200	Newest first
GET /v1/attractions/{id}/events, GET /v1/venues/{id}/events	50, 200	Start time, undated events last
GET /v1/calendar/items	50, 200	Chronological, or by prominence
GET /v1/webhooks/{webhookId}/deliveries	50, 200	Newest first
GET /v1/exports	25, 100	Newest first

Two collections page by id instead of by cursor: GET /v1/alerts/rules and GET /v1/alerts/events take before=<id> and return nextBefore, the id to pass next. A few endpoints return a bounded list in one response and take only limit: movers (up to 100), search (up to 20 per group) and calendar days.

Large pulls

Walking tens of thousands of rows page by page spends your request quota. For a full catalog or a long sales history, start an export instead: one request, one file.