Pagination

Most Orbit list endpoints use cursor-based pagination for consistent, efficient navigation through large result sets — cursors keep your iteration stable even as new rows arrive. A subset of dashboard-oriented endpoint families use offset-based pagination instead. This guide covers cursor-based pagination first, then the offset-based endpoints and how to tell which style an endpoint uses.

Overview

Every cursor-paginated response includes a pagination object in the meta field:

{
  "data": [...],
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-08T12:00:00Z",
    "pagination": {
      "cursor": "cur_msg_abc123",
      "has_more": true,
      "total": 1542
    }
  }
}

Field	Type	Description
`cursor`	string	Opaque cursor pointing to the last item in the current page
`has_more`	boolean	Whether more results exist beyond this page
`total`	integer	Total number of matching items (when available)

Quick Start

First Page

Request without a cursor to get the first page:

curl "https://api.orbit.devotel.io/api/v1/messages?limit=10" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Pass the cursor from the previous response to get the next page:

curl "https://api.orbit.devotel.io/api/v1/messages?limit=10&cursor=cur_msg_abc123" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Continue Until Done

Keep paginating until has_more is false.

Parameters

Cursor-paginated endpoints accept these pagination parameters:

Parameter	Type	Default	Description
`cursor`	string	—	Cursor from a previous response to fetch the next page
`limit`	integer	25	Number of items per page. The minimum is 1. The maximum depends on the endpoint: most cursor-paginated endpoints accept up to 200, and a few endpoint families cap lower (for example, 100). Stay within an endpoint’s documented maximum — check its API reference entry for the exact cap.

Examples

Node.js — Iterate All Messages

const orbit = new Devotel({ apiKey: 'dv_live_sk_xxxx' })

let cursor = undefined
let allMessages = []

do {
  const response = await orbit.messages.list({
    limit: 100,
    cursor,
    channel: 'sms',
  })

  allMessages = allMessages.concat(response.data)
  cursor = response.meta.pagination.has_more
    ? response.meta.pagination.cursor
    : undefined
} while (cursor)

console.log(`Fetched ${allMessages.length} messages`)

Python / Go / Other languages

First-party SDKs for Python, Go, Java, Ruby, PHP, and .NET are built and in beta but not yet published to their package registries. Until then, hit the REST endpoint directly (requests, httpx, net/http, OkHttp, etc.) — the cursor pattern above maps 1:1 onto any HTTP client.

Best Practices

Use a reasonable page size. Most cursor-paginated list endpoints accept a limit of up to 200; a few endpoint families cap lower (for example, 100). Offset-based endpoints set their own per-endpoint caps. Check the endpoint’s API reference entry for its exact maximum. For most use cases, 20–50 is sufficient.
Do not store cursors long-term. Cursors are opaque and may expire. They are meant for sequential iteration, not bookmarking.
Do not modify cursors. Cursors are server-generated tokens. Altering them will return a 400 Bad Request.
Handle empty pages. If a page returns an empty data array with has_more: false, iteration is complete.
Combine with filters. Apply query filters alongside pagination to narrow results before iterating:

curl "https://api.orbit.devotel.io/api/v1/messages?channel=sms&status=delivered&limit=50" \
  -H "X-API-Key: dv_live_sk_your_key_here"

Cursor vs. offset pagination

Orbit uses two pagination styles depending on the endpoint. Most list endpoints are cursor-based; a number of dashboard-oriented endpoint families use offset-based pagination instead.

	Cursor-based	Offset-based
Parameters	`cursor`, `limit`	`limit`, `offset`
Where the page metadata lives	`meta.pagination` (`cursor`, `has_more`, `total`)	the `data` envelope (`items`, `total`, `limit`, `offset`)
Consistency during concurrent writes	Stable	May skip or duplicate items across pages
Performance on large datasets	O(1) per page	Degrades as `offset` grows
Best for	Iterating an entire collection	Jumping to an arbitrary page in a bounded list

Cursor-based pagination is the default for high-volume, append-heavy collections (messages, notifications, audit logs, call lists, and most voice and messaging resources). Offset-based pagination is used where stable deep iteration matters less than jumping to a specific page.

Offset-based endpoints

Offset-based endpoints accept limit and offset query parameters and return the page inside the data envelope rather than in meta.pagination:

{
  "data": {
    "items": [...],
    "total": 1542,
    "limit": 50,
    "offset": 100
  }
}

Pass offset to skip rows and limit to size the page; total is the full count of matching rows. Offset depth is bounded on these endpoints (for example, the inbox ticket list caps offset at 10,000). To reach rows past the cap, narrow the result set with filters (status, date range) instead of paging deeper. Endpoint families that use offset-based pagination today:

Inbox tickets — GET /inbox/tickets, plus the ticket companies roll-up, comments, and history.
Contact data (CDP) — account profiles, account scoring, and contact relationships.
Compliance records.
Reports and analytics goals.
Surveys and referrals.
Admin — organization, routing, and agent administration.
Email suppressions.

All other list endpoints use cursor-based pagination as described above. When in doubt, check the response: a meta.pagination.cursor field means cursor-based; a data.offset field means offset-based.

WhatsApp

Guides

Pagination

Overview

Quick Start

First Page

Next Page

Continue Until Done

Parameters

Examples

Node.js — Iterate All Messages

Python / Go / Other languages

Best Practices

Offset-based endpoints

​Pagination

​Overview

​Quick Start

​First Page

​Next Page

​Continue Until Done

​Parameters

​Examples

​Node.js — Iterate All Messages

​Python / Go / Other languages

​Best Practices

​Cursor vs. offset pagination

​Offset-based endpoints

Pagination

Overview

Quick Start

First Page

Next Page

Continue Until Done

Parameters

Examples

Node.js — Iterate All Messages

Python / Go / Other languages

Best Practices

Cursor vs. offset pagination

Offset-based endpoints