How to Handle Pagination for the Synchronous Reports API

When you request data from the Reports API, the response may not include all available records if the dataset contains more than 1000 records. In such cases, the API returns a response with a status of TRUNCATED, indicating that additional records are available.

A TRUNCATED response includes a cursor and an iv (initialization vector), which are required to retrieve the next set of results.

You can handle pagination in two ways:

Use the _links.next.href URL provided in the response (recommended).
Manually pass the cursor and iv values into your next request.

You repeat this process until the API response is no longer TRUNCATED, meaning all records have been retrieved.

Initial Request

Here’s an example of an initial request to retrieve records:

GET https://api.nexmo.com/v2/reports/records?product=VERIFY-API&date_start=2025-10-28T00:00:00-0000&date_end=2025-10-30T00:00:00-0000&account_id=test123

Example of a TRUNCATED Response

If the result set contains more than 1000 records, the API responds with a "request_status": "TRUNCATED" value and includes the cursor, iv, and a next link to fetch the following page.

{
  "_links": {
    "next": {
      "href": "https://api.nexmo.com/v2/reports/records?product=VERIFY-API&date_start=2025-10-28T00%3A00%3A00-0000&date_end=2025-10-30T00%3A00%3A00-0000&account_id=test123&cursor=VwwxWeDsSHrf5eDbC7OA4NAUJKjy0Jw91uGIhbsjpH254R3Og6HCsfy5pmcw_Nzerlbt_p6J3xRxvocnv8CIoasCH0C3Z-Gq7n1VQ5Es6hgZKx4m0IN0G6lgqahNjoRoW67XysF32MGzYs2jkol1EmZ_o-TN5wvfILqGuDuXuUiUh-QvmmNPd5p066GTRxhuS6_DGRT-x7Lw2oxV&iv=QnJtvajk5bH0wMX-8JHLRQ"
    },
    "self": {
      "href": "https://api.nexmo.com/v2/reports/records?product=VERIFY-API&date_start=2025-10-28T00%3A00%3A00-0000&date_end=2025-10-30T00%3A00%3A00-0000&account_id=test123"
    }
  },
  "request_id": "aaaa111111-b222-4556-789c-fb123456789",
  "request_status": "TRUNCATED",
  "cursor": "VwwxWeDsSHrf5eDbC7OA4NAUJKjy0Jw91uGIhbsjpH254R3Og6HCsfy5pmcw_Nzerlbt_p6J3xRxvocnv8CIoasCH0C3Z-Gq7n1VQ5Es6hgZKx4m0IN0G6lgqahNjoRoW67XysF32MGzYs2jkol1EmZ_o-TN5wvfILqGuDuXuUiUh-QvmmNPd5p066GTRxhuS6_DGRT-x7Lw2oxV",
  "iv": "QnJtvajk5bH0wMX-8JHLRQ",
  "received_at": "2025-10-29T10:04:09+00:00",
  "price": 0.0,
  "currency": "",
  "product": "VERIFY-API",
  "account_id": "41aa7248",
  "date_start": "2025-10-28T00:00:00+00:00",
  "date_end": "2025-10-30T00:00:00+00:00",
  "items_count": 1000,
  "include_subaccounts": false,
  "records": [
    {
      "account_id": "test123",
      "request_id": "06a1e004a84e4b47ab48a15f072ef0dd",
      "from": "verify",
      "to": "123456789",
      "locale": "pl-pl",
      "number_type": "MOBILE",
      "network": "26003",
      "network_name": "Orange Polska S.A.",
      "country": "PL",
      "country_name": "Poland",
      "date_received": "2025-10-29T09:56:36+00:00",
      "date_finalized": "2025-10-29T10:01:49+00:00",
      "first_event_date": "2025-10-29T09:56:36+00:00",
      "last_event_date": "2025-10-29T10:01:43+00:00",
      "status": "EXPIRED",
      "sms_event_count": "1",
      "tts_event_count": "2",
      "currency": "",
      "pricing_model": "1",
      "price": "0.1",
      "estimated_price": "0.1",
      "sms_price": "0.03980000",
      "tts_price": "0.00238217",
      "id": "06a1e004a84e4b47ab48a15f072ef0dd"
    }
  ]
}

Fetching the Next Page

Whenever the response contains "request_status": "TRUNCATED", it means more results are available.

There are two ways to retrieve the next page:

Option 1 — Use the `next` Link (Recommended)

The easiest method is to send a

GET

request to the URL provided in the _links.next.href parameter from the TRUNCATED response, which is already configured with the correct cursor and iv values for your request:

GET https://api.nexmo.com/v2/reports/records?product=VERIFY-API&date_start=2025-10-28T00%3A00%3A00-0000&date_end=2025-10-30T00%3A00%3A00-0000&account_id=test123&cursor=VwwxWeDsSHrf5eDbC7OA4NAUJKjy0Jw91uGIhbsjpH254R3Og6HCsfy5pmcw_Nzerlbt_p6J3xRxvocnv8CIoasCH0C3Z-Gq7n1VQ5Es6hgZKx4m0IN0G6lgqahNjoRoW67XysF32MGzYs2jkol1EmZ_o-TN5wvfILqGuDuXuUiUh-QvmmNPd5p066GTRxhuS6_DGRT-x7Lw2oxV&iv=QnJtvajk5bH0wMX-8JHLRQ

Option 2 — Manually Add `cursor` and `iv`

If constructing requests manually, reuse all parameters from your initial request and append the cursor and iv values from the previous TRUNCATED response.

Continue Until All Records Are Retrieved

Each paginated response may also be TRUNCATED.
Continue following the next link (or using updated cursor/iv values) until the API response is no longer TRUNCATED.

This indicates that all available records have been retrieved.