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
| Parameter | Description |
|---|---|
limit | Page size; default 50, maximum 200 |
cursor | The next_cursor from the previous response; omit on the first page |
sort | Allowed 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 filters | E.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_cursorisnull. - 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
limitdue 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.
Idempotency
The Idempotency-Key header and idempotency_key field, 24-hour retention, same/different body behavior, the in-progress request lease, which operations support it, and automatic keys in the SDKs.
Versioning and compatibility
The /v1 compatibility promise, backward-compatible addition rules, breaking change policy and the new version path, deprecation, OpenAPI/SDK versions and the changelog.