Pagination of Large Results

Learn how to iterate through large result sets returned by Mobile Text Alerts API endpoints that return lists.

Many of the Mobile Text Alerts API endpoints return lists of records — subscribers, deliveries, webhooks, groups, dedicated numbers, templates, and more. To keep responses fast and predictable, these endpoints do not return every matching record at once. Instead, they return one page of results at a time, along with the metadata you need to request the next page.

All endpoints that return a list of results accept the following pagination parameters: page, pageSize, sortBy, and sortDirection. They also return the same structured paginated response. Once you learn the structure, it works the same way across all list-returning endpoints.

Why pagination matters at scale

A GET /subscribers call that returns 10,000+ subscribers would be slow and unwieldy as a single response. Pagination lets you pull those records in manageable batches. This lets you show progress, retry a single failed page, and stay within rate limits instead of timing out on one giant request.

Structure of a paginated response

All paginated endpoints wrap their results in a data object containing the page of records plus pagination metadata.

Example paginated response structure:

{
  "data": {
    "rows": [
      { "id": 109021633, "firstName": "Alex", "lastName": "Johnson" },
      { "id": 109021634, "firstName": "Sam", "lastName": "Lee" }
    ],
    "page": 0,
    "pageSize": 25,
    "total": 1340
  }
}

Field	Type	Description
rows	array	The array of records, the structure depends on the endpoint that is called (subscribers, deliveries, etc.).
page	number	The current page number. Note: Pages are 0-indexed.
pageSize	number	The number of records returned per page. If not specified, a default page size of 25 is used. Maximum value: 1000.
total	number	The total number of records matching your query across all pages — not just the current page. Use this to calculate how many pages you need to fetch.

0-Indexing

Because the first page is page: 0, the records on page p cover positions p * pageSize through (p + 1) * pageSize - 1. This matters for your loop condition (see below). So requesting page: 1 returns the second page.

Request a specific page

To request a specific page of a paginated response, pass the desired page and pageSize as query parameters on any list endpoint.

Example

To retrieve the third page of the GET /subscribers list (remember: 0-indexed) at 50 records per page:

curl --location 'https://api.mobile-text-alerts.com/v3/subscribers?page=2&pageSize=50' \
  --header 'Authorization: Bearer <APIKey>'

This returns records 100–149 (positions 2 * 50 through 3 * 50 - 1).

Sort page results

The two parameters below control the order in which records are returned. Note that sorting is applied before pagination, so the order is stable across pages.

Parameter	Type	Description
sortBy	string	The field to sort by. The set of sortable fields varies by endpoint (for example, the /deliveries endpoint sorts by date).
sortDirection	ASC | DESC	The sort direction. Indicate ASC for ascending or DESC for descending.

How a field sorts depends on its underlying type:

• text fields (such as firstName or email) sort alphabetically

• numeric and date fields (such as number or date) sort by numeric/chronological value

Check the individual endpoint's reference page for the fields it accepts in sortBy.

Example

To retrieve the list of GET /deliveries sorted by date in descending order:

curl --location 'https://api.mobile-text-alerts.com/v3/deliveries?sortBy=date&sortDirection=DESC' \
  --header 'Authorization: Bearer <APIKey>'

How to fetch all pages

This pattern is the same for all list endpoint results: start at page: 0, read total from the first response, then keep incrementing page until you have fetched every record.

Example

The example below pages through GET /subscribers, but you can change the path to any list endpoint.

Pages are 0-indexed, so there are records to retrieve as long as page * pageSize < total — so you stop once page * pageSize >= total.

Node.js

Requirements: Node.js 18+ (native fetch) and an MTA_API_KEY environment variable.

const BASE_URL = "https://api.mobile-text-alerts.com/v3";
const API_KEY = process.env.MTA_API_KEY;

async function fetchAllSubscribers({
  pageSize = 100,
  query,
  sortBy,
  sortDirection,
} = {}) {
  const all = [];
  let page = 0;
  let total = Infinity; // unknown until the first response

  while (page * pageSize < total) {
    const params = new URLSearchParams({ page, pageSize });
    if (query) params.set("query", query);
    if (sortBy) params.set("sortBy", sortBy);
    if (sortDirection) params.set("sortDirection", sortDirection);

    const res = await fetch(`${BASE_URL}/subscribers?${params}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });
    if (!res.ok) throw new Error(`Request failed: ${res.status}`);

    const { data } = await res.json();
    total = data.total;       // cache total from the first response onward
    all.push(...data.rows);

    if (data.rows.length === 0) break; // safety: stop on an empty page
    page += 1;

    // Be gentle on rate limits when fetching many pages
    await new Promise((r) => setTimeout(r, 250));
  }

  return all;
}

fetchAllSubscribers({ pageSize: 100 })
  .then((rows) => console.log(`Fetched ${rows.length} subscribers`))
  .catch((err) => console.error(err));

Python

Filter results

You can narrow a list before paginating it, so you only page through the records you actually need.

• query — A free-text search string.

  • For example, on GET /subscribers, the query value matches against firstName, lastName, number, and email (and custom subscriber fields), returning any subscriber where it appears.

• filters — A structured object for endpoint-specific filtering. The available filter keys vary by endpoint.

  • For example, GET /deliveries accepts filters[status], filters[type], filters[startDate], and filters[endDate]. Pass them as bracketed query parameters (?filters[status]=delivered).

Filter options differ by endpoint. See each endpoint's reference page for the full list. Filters and sorting can be combined with pagination in the same request.

Paginated list best practices

• Use reasonable page sizes — Typically, use 50–100 records per page. This strikes a good balance between fewer requests and faster response handling. The maximum is 1000, but larger page sizes increase response size and latency per request.

• Respect rate limits — Most endpoints allow 30 requests per minute per IP, and GET /subscribers is further limited to 15 requests every 15 seconds. When fetching many pages, add a short delay between requests and watch the X-RateLimit-Remaining and Retry-After response headers to avoid a 429 response.

• Cache total from the first response — Read total once on the first page and reuse it to calculate the number of pages and report progress (for example, page * pageSize / total) rather than re-deriving it on every request.

• Use bulk endpoints for very large writes — Pagination is for reading. If you need to add or remove large numbers of records, use the bulk endpoints where available, such as Bulk Create/Update Subscribers (POST/PATCH /subscribers/bulk) or Bulk Add/Delete group subscribers. These accept up to 1,000 records per request and are far more efficient than per-record calls.