Pagination

In this guide, we will look at how to work with paginated responses when querying the xNumbers API. By default, all list responses limit results to ten items per page. However, you can go as high as 100 by adding a limit parameter to your requests.

When an API response returns a list of objects, pagination is supported. The xNumbers API uses page-based pagination: objects are nested in a data attribute, and a meta object describes where you are in the resultset. You move through pages with the page and limit query parameters.

Example using page and limit

In this example, we request page 2 of the numbers assigned to the customer acme, ten at a time. The meta object tells us the total number of matching items, how many pages there are, and whether there is a next or previous page.

Name
page
Type
integer
Description
The page number to fetch (1-based). Defaults to 1.
Name
limit
Type
integer
Description
The number of items per page. Defaults to 10, with a maximum of 100.

Most list endpoints also accept search, sort_by, and sort_order (asc/desc) query parameters alongside the pagination parameters, plus resource-specific filters (for example status on numbers and users).

GET

/customers/{customer_slug}/numbers

curl -G https://api.xnumbers.io/api/customers/acme/numbers \
  -H "Authorization: Bearer xn_YOUR_API_KEY" \
  -d page=2 \
  -d limit=10

Paginated response

{
  "data": [
    {
      "number_id": "123e4567-e89b-12d3-a456-426614174000"
      // ...
    },
    {
      "number_id": "223e4567-e89b-12d3-a456-426614174001"
      // ...
    }
  ],
  "meta": {
    "total": 150,
    "page": 2,
    "limit": 10,
    "totalPages": 15,
    "hasNextPage": true,
    "hasPreviousPage": true
  }
}

The meta object

Every paginated response carries the same core meta shape.

Name
total
Type
integer
Description
Total number of items matching the query, across all pages.
Name
page
Type
integer
Description
The current page number.
Name
limit
Type
integer
Description
The number of items per page used for this response.
Name
totalPages
Type
integer
Description
Total number of pages for the current limit.
Name
hasNextPage
Type
boolean
Description
Whether a next page exists. Stop paginating when this is false.
Name
hasPreviousPage
Type
boolean
Description
Whether a previous page exists.

Some list endpoints extend meta with extra summary fields - for example, /customers/{customer_slug}/users includes a status_counts object with per-status totals, and the customer orders list does the same. The core fields above are always present.

meta with resource-specific extras (users list)

{
  "meta": {
    "total": 12,
    "page": 1,
    "limit": 10,
    "totalPages": 2,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "status_counts": {
      "active": 9,
      "inactive": 2,
      "locked": 1
    }
  }
}