Pagination

What you'll buildCopy Anchor Link

A loop that reads a whole list one page at a time, and a poller that only fetches what is new.

PrerequisitesCopy Anchor Link

• A secret API key with the scope of the list you read (messages:read, events:read, webhooks:manage or logs:read). See Authentication and API keys.
• curl, Node.js 18 or later with @voicelayer/api, or Python 3.9 or later with voicelayer.

How cursors workCopy Anchor Link

Lists return a page and a cursor. Pass the cursor back to get the next page. Cursors are opaque: store them as they are, never build or change one. A cursor the API did not issue is refused with 400.

Set the page size with limit.

Step 1: Read the first pageCopy Anchor Link

curl "https://api.vlayers.ai/v1/conversations?controller=human&limit=20" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"

{
  "conversations": [
    {
      "id": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",
      "channel": "sms",
      "lineId": "0192f5a8-1a2b-7c3d-8e4f-5a6b7c8d9e01",
      "bindingId": null,
      "peer": {
        "address": "+15550123"
      },
      "controller": "api",
      "status": "open",
      "openedAt": "2026-10-20T15:04:05.000Z",
      "lastActivityAt": "2026-10-20T15:04:05.000Z",
      "test": true
    }
  ],
  "nextCursor": null
}

Step 2: Follow the cursorCopy Anchor Link

Pass nextCursor back as cursor until it is null:

export NEXT_CURSOR=<the nextCursor you got>

curl "https://api.vlayers.ai/v1/conversations?cursor=$NEXT_CURSOR&limit=50" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"

Step 3: Show a chat history, newest firstCopy Anchor Link

For a conversation's messages, start with before=end for the newest page. Each page is still in time order (oldest first). Pass its prevCursor as before for the page before it; prevCursor is null when nothing older is left.

export CONVERSATION_ID=<the conversation's id>

curl "https://api.vlayers.ai/v1/conversations/$CONVERSATION_ID/messages?before=end&limit=20" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"

Step 4: Poll for what is newCopy Anchor Link

Keep the last nextCursor (messages) or cursor (events) and pass it as after next time. On an empty page the cursor stays where it was, so a poller never loses its place. For events, add waitSec to wait for the next one instead of polling in a tight loop:

curl "https://api.vlayers.ai/v1/events?after=$CURSOR&waitSec=20" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"

Test itCopy Anchor Link

With a test key, simulate a few messages with POST /v1/test/inbound (see Test mode), then page through GET /v1/messages with limit=1.

Common errorsCopy Anchor Link

Next stepsCopy Anchor Link

• Stream events: no polling at all.
• Rate limits.
• API reference.