Pagination
Read customer records, campaign runs, and other lists one page at a time. Each response returns results in data and the next-step information in pagination. Most lists use offset pagination with limit and offset. The events list (GET /v1/events) is the exception: it uses cursor pagination.
Offset pagination
Pass limit and offset as query parameters. The response wraps the page in data and reports the window in pagination.
Parameters
- Name
limit- Type
- integer
- Description
Page size. Default
50. Clamped to the range1..200with a warning if out of range.
- Name
offset- Type
- integer
- Description
Rows to skip. Default
0. Values below0are clamped to0with a warning. A value above10000is rejected with400 offset_too_large, not clamped.
Response
- Name
data- Type
- array
- Description
The page of results.
- Name
pagination.limit- Type
- integer
- Description
The applied page size.
- Name
pagination.offset- Type
- integer
- Description
The applied offset.
- Name
pagination.totalCount- Type
- integer
- Description
Total rows matching the query, across all pages.
- Name
pagination.hasMore- Type
- boolean
- Description
truewhen more rows exist and the next offset is below10000. A false value can mean the traversal cap was reached, even whentotalCountis larger.
curl "https://api.maxclicks.ai/v1/schemas/customers/records?limit=50&offset=100" \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"
Replace customers with your schema slug. Page forward by advancing offset by the returned pagination.limit while pagination.hasMore is true. offset cannot exceed 10000, and normal traversal stops before the next offset reaches that cap. This is not an unlimited export API. The records list has no ad-hoc filter or time-range parameter; use a suitable segment where supported, or arrange a full export in the app instead of inventing query fields.
Endpoints
Offset pagination applies to every list except GET /v1/events: schemas.list, attributes.list, records.list, records.auditTrail, suppressions.list, domains.list, senders.list, topics.list, segments.list, segments.listContacts, broadcasts.list, broadcasts.listRuns, templates.list, webhooks.list, workflows.list, and workflows.listRuns.
segments.listContacts is the one endpoint with a lower ceiling: it caps the page at 100 rows whatever limit you send, and it emits no warning when it truncates. Ask for 200 there and you get 100 rows back with pagination.limit reporting 100. Use the returned page size when advancing the offset.
Cursor pagination
GET /v1/events returns only ready business events, ordered by occurredAt descending and then id descending. It has no offset and no totalCount. Instead, each page returns an opaque nextCursor that you pass back as cursor to fetch the next page.
Parameters
- Name
limit- Type
- integer
- Description
Page size. Default
50, capped at200.
- Name
cursor- Type
- string
- Description
Opaque cursor from the previous page's
pagination.nextCursor. Omit for the first page. An invalid value returns400 invalid_cursor.
Response
- Name
data- Type
- array
- Description
The page of events.
- Name
pagination.limit- Type
- integer
- Description
The applied page size.
- Name
pagination.nextCursor- Type
- string | null
- Description
Cursor for the next page, or
nullwhen no more rows exist.
- Name
pagination.hasMore- Type
- boolean
- Description
truewhen another cursor page is available.
curl "https://api.maxclicks.ai/v1/events?schema=purchase-completed&limit=50" \
-H "Authorization: Bearer $MAXCLICKS_API_KEY"
Loop until pagination.hasMore is false (or nextCursor is null), passing the returned nextCursor as cursor each time. Set explicit from and to timestamps on your first request, and keep schema, from, to, and limit fixed across pages. This avoids a moving default time window during a long export.
The events list reads the operational event store. from is inclusive and
to is exclusive; defaults are the last 7 days. A range wider than 90 days is
clamped with a warning. Pending, failed, and unresolved events are absent; use
event readiness to inspect an acceptance.
Workflow step history
A workflow run embeds at most 100 step-history records. Its initial window is the latest 100, ordered by index ascending within that window. To inspect earlier execution, call GET /v1/workflows/{id}/runs/{runId}?history_before=... with the returned nextHistoryBeforeIndex. Continue until that field is null. This cursor is separate from the offset pagination of the run list. stepCount is the execution ordinal, not the number of entries in one window.