Skip to content

Pagination

List endpoints use opaque cursors, so pages stay stable even while new data arrives.

Request

Body parameters
  • limitintegeroptional
    Items per page. The default and maximum depend on the endpoint (below); values out of range are clamped.
  • cursorstringoptional
    The next_cursor value from the previous page. Omit for the first page.
EndpointDefaultMax
GET /v1/contacts50200
GET /v1/conversations30100
GET /v1/conversations/{id}/messages50200
GET /v1/campaigns30100
GET /v1/media40100
GET /v1/webhooks/{id}/deliveries50200

Short collections — templates, numbers, tags, lists, segments, attributes, webhook endpoints — are returned whole as { "data": [...] } with no cursor.

Response

GET /v1/contacts?limit=2
{
  "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