Pagination

Read the endpoint’s pagination fields before walking a collection. Main API lists do not all use the same cursor names, defaults, or sort options. Keep filters and ordering unchanged while following a cursor.

Choose the endpoint contract

Collection	Default page size	Next and previous fields	Ordering
Contact lists and other lists using the common pagination contract	25	`nextCursor`, `prevCursor`	Endpoint-specific `sort` and `direction=asc` or `desc`; `page=next` or `prev` selects traversal
Events	50	`nextCursor`, `prevCursor`	`direction=desc` by default; `asc` is supported
Event aggregation groups	50	`nextCursor`, `prevCursor`	Determined by the requested grouping
Campaign recipient messages	25	`next`, `prev`	`sort=send_at`, `direction=desc` by default; `asc` is supported

These contracts allow pages up to 100 results. The common pagination schema also exposes limit=-1; prefer bounded pages for bulk work. Event queries and campaign recipient messages require a positive page size and do not support that option. Use a returned cursor as the next request’s cursor. Common lists also use page=prev when traversing backwards. Event and campaign-recipient cursors encode their traversal information. Treat a missing or null next cursor as the end of the collection.

Walk a contact list

Fetch each page before requesting the next one:

async function* listContacts(token) {
  let cursor
  do {
    const url = new URL('https://apix.spotzee.com/api/client/users')
    url.searchParams.set('limit', '100')
    if (cursor) url.searchParams.set('cursor', cursor)

    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${token}` }
    })
    if (!response.ok) throw new Error(`Request failed: ${response.status}`)
    const page = await response.json()
    yield* page.results
    cursor = page.nextCursor
  } while (cursor)
}

Pass your project secret API key as token. The /users path names contact records, not team members. This generator yields each page’s contacts and stops when no next cursor is returned.

Sort and filter

Use separate sort and direction parameters where the endpoint supports them. For example, contact lists default to sort=id and direction=desc. Do not prefix a sort field with - or use forward and backward as sort directions. Filters are endpoint-specific. Event queries require a bounded time window and at least one supported selective filter. Campaign recipient queries accept a bounce_category filter; event queries do not. Use the generated endpoint reference for the accepted parameters.

Interpret changing results

Pagination does not freeze the collection. Records can arrive, change, or disappear between requests. A cursor is a continuation token, not a guarantee that a changing collection cannot produce gaps or repeated records. Persist record identifiers when your integration needs to reconcile repeated reads. Do not assume every endpoint returns total-count or page-index headers. Follow the response body and the endpoint’s documented fields. Event aggregate count values count occurrences; campaign bounced-message totals count messages.

Get started

Build

Configure

SDKs

Integrate

Reporting

Tools

API conventions

Recipes

Choose the endpoint contract

Walk a contact list

Sort and filter

Interpret changing results

Next steps

Query events

Campaign bounce reporting

​Choose the endpoint contract

​Walk a contact list

​Sort and filter

​Interpret changing results

​Next steps

Query events

Campaign bounce reporting

Choose the endpoint contract

Walk a contact list

Sort and filter

Interpret changing results

Next steps