PushizoDocs
API reference

Pagination, filtering and sorting

Cursor-based listing (limit, cursor, next_cursor, has_more), cursor format and validity, filter[...] and sort parameters, and helpers in the SDKs for iterating over all pages.

List endpoints are cursor-based: there are no page numbers; each response gives you the cursor for the next page. This approach is consistent and fast on large tables (newly added records don't shift pages).

Request

ParameterDescription
limitPage size; default 50, maximum 200
cursorThe next_cursor from the previous response; omit on the first page
sortAllowed fields depend on the endpoint; a - prefix means descending (e.g. sort=-created_at, last_active_at on the user list)
filter[field]=value / endpoint-specific filtersE.g. GET /v1/notifications?status=completed&source=campaign, GET …/users?tag=plan:pro&last_active_after=2026-10-01T00:00:00Z, GET …/suppressions?channel=email&reason=bounce

Response

{
  "data": [ { "id": "msg_01J…", "…": "…" } ],
  "next_cursor": "eyJpZCI6Im1zZ18wMUouLi4ifQ",
  "has_more": true
}
  • If has_more: false, you are on the last page; next_cursor is null.
  • The cursor is an opaque base64url-encoded value containing the ID of the last record (and the sort key, if any); don't write code that depends on its contents. An invalid cursor, or one produced with a different sort order, returns 400 HS_VALIDATION_ERROR (details.field: cursor).
  • Cursors don't expire; however, the page size may be smaller than limit due to deletions in between.
curl "https://api.pushizo.com/v1/apps/app_…/users?limit=100&sort=-last_active_at" -H "Authorization: Bearer $PUSHIZO_API_KEY"
curl "https://api.pushizo.com/v1/apps/app_…/users?limit=100&sort=-last_active_at&cursor=eyJpZCI6…" -H "Authorization: Bearer $PUSHIZO_API_KEY"

SDK helpers

All server SDKs provide helpers that iterate over pages item by item:

for await (const user of hs.paginate((cursor) => hs.users.list({ cursor, limit: 200 }))) {
  // user
}

The helper keeps following next_cursor until has_more is false; retries use the same cursor. For large bulk extractions, CSV export is more efficient than pagination.

On this page