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`)

TypeScript — Node SDK with cursor types

The response.meta.pagination cursor fields are typed, so the loop below compiles against the SDK’s list-response shape instead of any:

import { Devotel } from '@devotel-orbit/node'

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

let cursor: string | undefined
const allMessages = []

do {
  const response = await orbit.messages.list({ limit: 100, cursor })
  allMessages.push(...response.data)
  cursor = response.meta.pagination.has_more
    ? response.meta.pagination.cursor
    : undefined
} while (cursor)

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

Python

The Python SDK is published (pip install devotel-orbit-sdk). Iterate with the client.request(...) escape hatch — pagination is the same shape on every cursor endpoint:

from orbit_sdk import OrbitClient, OrbitError

client = OrbitClient.from_env()
params = {"channel": "sms", "limit": 100}
total = 0

try:
    while True:
        page = client.request("GET", "/messages", params=params)
        total += len(page.get("data", []))
        pagination = page["meta"]["pagination"]
        if not pagination["has_more"]:
            break
        params["cursor"] = pagination["cursor"]
except OrbitError as exc:
    print(f"list failed: {exc.code} - {exc.message}")

Go

Install the published module with go get github.com/devotel/orbit-go/orbit@latest, then loop the cursor as query values. The listResponse struct below is the shape every cursor endpoint shares:

client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
if err != nil {
	// handle
}

query := url.Values{}
query.Set("channel", "sms")
query.Set("limit", "100")

type listResponse struct {
	Data []map[string]any `json:"data"`
	Meta struct {
		Pagination struct {
			Cursor  string `json:"cursor"`
			HasMore bool   `json:"has_more"`
		} `json:"pagination"`
	} `json:"meta"`
}

total := 0
for {
	var page listResponse
	if err := client.Request(context.Background(), "GET", "/messages", query, nil, &page, ""); err != nil {
		// handle
		break
	}
	total += len(page.Data)
	if !page.Meta.Pagination.HasMore {
		break
	}
	query.Set("cursor", page.Meta.Pagination.Cursor)
}

Ruby

The Ruby gem is built but not yet published to RubyGems — until it ships, iterate the same cursor with stdlib Net::HTTP:

require "net/http"
require "json"

uri = URI("https://api.orbit.devotel.io/api/v1/messages")
params = { "channel" => "sms", "limit" => "100" }
total = 0

loop do
  uri.query = URI.encode_www_form(params)
  response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
    http.request(Net::HTTP::Get.new(uri, "X-API-Key" => ENV.fetch("ORBIT_API_KEY")))
  end

  page = JSON.parse(response.body)
  total += page.fetch("data", []).length
  pagination = page.dig("meta", "pagination") || {}
  break unless pagination["has_more"]

  params["cursor"] = pagination["cursor"]
end

puts "Fetched #{total} messages"

PHP

The PHP SDK’s low-level request() hatch keeps the loop the same shape as the Python example above:

<?php

$client = Devotel\Orbit\Client::fromEnv();
$params = ['channel' => 'sms', 'limit' => 100];
$total = 0;

do {
    $page = $client->request('GET', '/messages', ['query' => $params]);
    $total += count($page['data'] ?? []);
    $pagination = $page['meta']['pagination'];
    $params['cursor'] = $pagination['cursor'];
} while ($pagination['has_more']);

echo "Fetched {$total} messages", PHP_EOL;

Other languages

Go, Java, Ruby, PHP, and .NET SDKs are built but not yet published to their package registries — until then, hit the REST endpoint directly (urllib, OkHttp, etc.) — the cursor pattern above maps 1:1 onto any HTTP client.

Edge cases

has_more=false and an empty final page are the normal end of a cursor iteration, not an error condition. The loop below retries rate-limited requests with exponential backoff and terminates on has_more=false, including when the last page carries no rows:

import time

# client and OrbitError from the Python example above
params = {"channel": "sms", "limit": 100}
total = 0

while True:
    for attempt in range(4):
        try:
            page = client.request("GET", "/messages", params=params)
            break
        except OrbitError as exc:
            if exc.code != "rate_limited" or attempt == 3:
                raise
            time.sleep(2 ** attempt)

    total += len(page.get("data", []))
    pagination = page["meta"]["pagination"]

    # An empty page with has_more=false is the end of the collection.
    if not pagination["has_more"]:
        break

    params["cursor"] = pagination["cursor"]

print(f"Fetched {total} messages")

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.

Example: paging the opt-out list

The opt-out list offset-paginates. Page until the accumulated rows reach total — offset responses carry no has_more flag:

curl "https://api.orbit.devotel.io/api/v1/optouts?limit=50&offset=0" \
  -H "X-API-Key: dv_live_sk_your_key_here"

let offset = 0
const limit = 50
let items = []

while (true) {
  const res = await fetch(
    `https://api.orbit.devotel.io/api/v1/optouts?limit=${limit}&offset=${offset}`,
    { headers: { 'X-API-Key': process.env.ORBIT_API_KEY } },
  )
  const page = await res.json()
  items = items.concat(page.data.items)
  if (items.length >= page.data.total) break
  offset += limit
}

import json
import os
import urllib.request

offset, limit, items = 0, 50, []
while True:
    url = f"https://api.orbit.devotel.io/api/v1/optouts?limit={limit}&offset={offset}"
    request = urllib.request.Request(
        url, headers={"X-API-Key": os.environ["ORBIT_API_KEY"]}
    )
    with urllib.request.urlopen(request) as response:
        page = json.load(response)
    items += page["data"]["items"]
    if len(items) >= page["data"]["total"]:
        break
    offset += limit

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

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

Pagination: cursor and offset paging in the Orbit API

Overview

Quick Start

First Page

Next Page

Continue Until Done

Parameters

Examples

Node.js — Iterate All Messages

TypeScript — Node SDK with cursor types

Python

Go

Ruby

PHP

Other languages

Edge cases

Best Practices

Offset-based endpoints

Example: paging the opt-out list

​Pagination

​Overview

​Quick Start

​First Page

​Next Page

​Continue Until Done

​Parameters

​Examples

​Node.js — Iterate All Messages

​TypeScript — Node SDK with cursor types

​Python

​Go

​Ruby

​PHP

​Other languages

​Edge cases

​Best Practices

​Cursor vs. offset pagination

​Offset-based endpoints

​Example: paging the opt-out list

Pagination

Overview

Quick Start

First Page

Next Page

Continue Until Done

Parameters

Examples

Node.js — Iterate All Messages

TypeScript — Node SDK with cursor types

Python

Go

Ruby

PHP

Other languages

Edge cases

Best Practices

Cursor vs. offset pagination

Offset-based endpoints

Example: paging the opt-out list