Offset pagination
total, page, and per_page values to decide whether another page exists. Respect endpoint maximums.
Page and limit on array lists
Some lists return a plain JSON array. They takelimit (page size, up to 200) and page (starting at 1), and report where you are in response headers: X-Total-Count (every matching row), X-Page and X-Per-Page. Stop when page * limit reaches X-Total-Count.
GET /agents?type=chat, which takes page and per_page). List connected channel accounts returns an object; its total counts every matching account and page and limit select the slice.
Time cursor on activity timelines
Get one lead withinclude=activities to read its timeline, newest first, up to activities_limit events (default 200, maximum 500). When older events remain, the lead carries an activities_next_cursor value. Send it back as activities_before to read the next page; no cursor means you have reached the start.
502 instead of a partial list.
Cursor pagination
next_cursor back unchanged. Cursors are opaque: do not decode, sort, or construct them.
Safe collection loops
- Keep filters and sort parameters unchanged on every page.
- Store the last cursor before processing records.
- Deduplicate by public
idwhen consuming pages asynchronously. - Handle
429and5xxresponses without advancing the cursor.