Skip to content
CatalystCatalyst Docs

Pagination

Pagination is per-endpoint, not universal

Section titled “Pagination is per-endpoint, not universal”

Catalyst does not use one pagination scheme everywhere. Check the endpoint in the API reference before writing generic page-walking code.

page + limit with a pagination block

Section titled “page + limit with a pagination block”

GET /api/admin/users, GET /api/admin/servers, GET /api/alerts, and GET /api/nodes/:id/allocations always return a pagination object:

{
  "servers": [ ... ],
  "pagination": { "page": 1, "limit": 20, "total": 84, "totalPages": 5 }
}
Endpoint page default limit default limit cap
GET /api/admin/users 1 20 100
GET /api/admin/servers 1 20 100
GET /api/alerts 1 50 100
GET /api/nodes/:id/allocations 1 50 100

These also accept filters such as search (/api/admin/users, /api/admin/servers), status, and owner (/api/admin/servers).

Terminal window
curl -H "Authorization: Bearer $CATALYST_API_KEY" \
  "https://panel.example.com/api/admin/servers?page=2&limit=50&search=survival"

Endpoints built on the shared pagination helper — GET /api/servers/:id/tasks, GET /api/alerts/:id/deliveries, and GET /api/nodes/:id (its server list) — add the same pagination block only when you pass page or limit; without them they return the whole collection. page defaults to 1 and limit to 50, capped at 100.

page + limit with flat counts

Section titled “page + limit with flat counts”

GET /api/servers/:serverId/backups returns backups plus flat total, page, pageSize, and totalPages fields. page defaults to 1, limit to 50, capped at 100.

limit + offset returning { success, data }

Section titled “limit + offset returning { success, data }”

GET /api/servers uses an offset cursor instead of pages:

Terminal window
curl -H "Authorization: Bearer $CATALYST_API_KEY" \
  "https://panel.example.com/api/servers?limit=50&offset=100"
{ "success": true, "data": [ ... ] }

limit defaults to 50 (max 500); offset defaults to 0. GET /api/templates accepts the same limit/offset (max 100) and returns all templates when limit is omitted.

Full lists

Section titled “Full lists”

Some collections are returned whole and ignore pagination parameters: nodes, locations, nests, roles, and server allocations. Do not assume total or pagination is present on those responses.

Rules

Section titled “Rules”
  • Cap your limit. Ask for what you will display (20–100). Full exports belong in bulk endpoints or repeated pages, not limit=100000.
  • Paginate to exhaustion (page++ until a short or empty page, or advance offset by the rows returned) rather than trusting a total — totals shift while you read, so reconcile sync jobs instead of assuming a stable window.
  • Cache sparingly. Lists change constantly (server states, node health). Cache seconds, not hours, or re-fetch on user action.
Section titled “Related”