Pagination

Every list endpoint in the v1 API uses cursor-based pagination. Cursors are opaque to clients — they’re HMAC-signed tokens encoding the sort key of the last record on the page. You don’t need to (and shouldn’t) decode or construct them yourself.

Query parameters

Parameter	Type	Default	Max	Description
limit	integer	25	100	Number of records to return per page.
cursor	string	-	-	Opaque cursor returned by a previous page in meta.pagination.cursor.

Response shape

List responses include a pagination object inside meta:

{
  "data": [
    /* records */
  ],
  "meta": {
    "request_id": "req_8f3c1b2a",
    "pagination": {
      "cursor": "eyJpZCI6NDIsImMiOiIyMDI2LTA0LTAxVDE1OjMyOjExWiJ9.7e4f...",
      "has_more": true,
      "count": 25
    }
  }
}

• cursor — Pass to the next request to get the next page. null on the last page.
• has_more — true if there are more records after this page.
• count — Number of records in the current page.

Why keyset cursors?

Cursors encode the sort key of the last seen record (id + createdAt) and are HMAC-signed so the server can detect tampering. Compared to offset/limit pagination, keyset cursors give you:

• Consistency under writes. New records inserted while you’re paginating won’t shift items between pages or cause duplicates.
• Stable performance. The server can use an indexed range scan instead of skipping rows. Pages 1 and 1000 cost the same.
• No skew on deletions. Soft-deleted records don’t shift the offset.

Caution

Cursors are opaque and HMAC-signed. Don’t try to decode, parse, or hand-craft them — the server will reject anything it didn’t sign.

Looping through every page

async function* listAllContacts(apiKey) {
  let cursor = null;
  do {
    const url = new URL('https://app.buildworkpro.com/api/v1/contacts');
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const body = await res.json();

    for (const contact of body.data) yield contact;

    cursor = body.meta.pagination.has_more ? body.meta.pagination.cursor : null;
  } while (cursor);
}

for await (const contact of listAllContacts(process.env.BUILDWORKPRO_API_KEY)) {
  console.log(contact.email);
}