Pagination
List endpoints use opaque cursors, so pages stay stable even while new data arrives.
Request
Body parameters
limitintegeroptionalItems per page. The default and maximum depend on the endpoint (below); values out of range are clamped.cursorstringoptionalThenext_cursorvalue from the previous page. Omit for the first page.
Short collections — templates, numbers, tags, lists, segments, attributes, webhook endpoints — are returned whole as { "data": [...] } with no cursor.
Response
GET /v1/contacts?limit=2
JSON
{
"data": [
{ "id": "b1e7…", "name": "Jane Doe", "phone": "14155550101" },
{ "id": "c9a2…", "name": "Sam Wilson", "phone": "14155550102" }
],
"next_cursor": "eyJjIjoiMjAyNi0xMS0xMVQxMDo0MjowMFoiLCJpIjoiYzlhMiJ9",
"total": 48210
}When next_cursor is null you have reached the last page. Treat cursors as opaque strings — don't parse or construct them. An invalid cursor returns 422. Filters (e.g. q, tag) must be repeated unchanged on every page. The contacts list also returns total on the first page.
A conversation's message history pages backwards in time: pass the next_cursor you received as before instead of cursor.
Iterating all pages
async function* allContacts() {
let cursor = null;
do {
const url = new URL("https://engage.swastik.ai/v1/contacts");
url.searchParams.set("limit", "200");
if (cursor) url.searchParams.set("cursor", cursor);
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.ENGAGE_API_KEY}` } });
const page = await res.json();
yield* page.data;
cursor = page.next_cursor;
} while (cursor);
}
for await (const c of allContacts()) console.log(c.name);Something unclear or missing on this page? Tell us at contact@swastik.ai