Skip to main content

How It Works

The API v2 uses cursor-based pagination for all list endpoints. Cursors are opaque, base64-encoded strings — treat them as opaque tokens and do not attempt to decode or construct them.

Query Parameters

Response Shape

All paginated responses follow this structure:

Paginating Through All Results

Pass the cursor from each response into the next request to iterate through all pages:

Export Pagination

The export endpoint (GET /api/v2/agents/{agentId}/conversations/export) paginates through all conversations (from every source) with full message history included. Each page returns up to limit conversations with their complete messages already embedded — no separate call to a messages endpoint is needed.
Because each exported conversation includes all of its messages, pages can be significantly larger than other paginated responses. Use a smaller limit if you want to keep response sizes manageable.

Message Pagination

The messages endpoint (GET /api/v2/agents/{agentId}/conversations/{conversationId}/messages) paginates backward from the newest messages. Within each page, messages are returned in chronological order. This means:
  • The first page contains the most recent messages
  • Passing the cursor fetches the next older page
  • Each page’s messages are ordered oldest → newest
The cursor returned by the Get a conversation endpoint is compatible with the messages endpoint, so you can use it to fetch older messages beyond what the conversation response includes.

Attendance and Activity Pagination

List attendance rows and List activity segments differ from the other lists:
  • limit goes from 1 to 1000 and defaults to 100.
  • The response has no pagination.total.
  • One request covers at most 31 days, from startDate to endDate. Read a longer history as several ranges.
  • A cursor only works with the startDate, endDate and timezone it came from. Changing any of them returns 400 VALIDATION_CURSOR_QUERY_MISMATCH.
  • The two share a limit of 30 calls per 10 seconds per account. See Rate limit.
The loops above already handle this, because they stop only when cursor is null. See Attendance and activity for an example.