API conventions: pagination, filtering, and sorting
Understand the shared request and response patterns used across all endpoints.
List endpoints share a common contract for paging through large result sets, narrowing results, and ordering them. Learning these conventions once means you can call any collection endpoint consistently. Parameter names and limits vary by product edition, so treat the values below as representative and (confirm the exact names and defaults in your account's API documentation).
Reference
| Convention | Typical parameter(s) | Example | Notes |
|---|---|---|---|
| Page-based paging | page, pageSize | ?page=2&pageSize=50 | 1-based page index. A default page size is applied when omitted. |
| Offset paging | limit, offset | ?limit=50&offset=100 | Alternative to page-based paging on some endpoints. |
| Cursor paging | cursor (or nextToken) | ?cursor=eyJpZCI6MTIzfQ | Follow the cursor returned in the previous response; treat it as opaque. |
| Result metadata | response envelope | { "data": [...], "total": 240, "page": 2, "pageSize": 50 } | Use the returned total/next cursor rather than counting rows yourself. |
| Filtering | filter[field] or field | ?filter[status]=sent | Combine multiple filters to narrow results; unknown fields are ignored or rejected. |
| Range filtering | <field>From, <field>To | ?createdFrom=2026-06-01&createdTo=2026-06-30 | Use ISO 8601 UTC dates/times for ranges. |
| Sorting | sort | ?sort=-createdAt | Comma-separate multiple keys; a leading - denotes descending order. |
Notes
- Defaults and caps. When you omit paging parameters a default page size applies, and there is usually a maximum page size. Requesting more than the cap returns the cap, not an error.
- Stable ordering. Always pass an explicit
sortwhen paging. Without it, ordering is not guaranteed and rows can shift between pages. - Empty results. A valid query that matches nothing returns an empty
dataarray with a success status, not an error. - Dates and timezones. Send and expect timestamps in ISO 8601, UTC. Client-local times can cause off-by-a-day range filters.
- URL encoding. Encode filter values (spaces,
+,&, non-ASCII) so they survive as query-string parameters. - Forward compatibility. New fields may appear in responses over time. Parse defensively and ignore unrecognized keys rather than failing.
Related
Canonical terms: Author, Edition, Folder (Project Folder), Broadcast. See the Glossary.