Pagination

You can use the pagination to limit the number of the objects returned in the response and sort them by the object attributes.

Pagination is available for the GET requests which return the lists of the objects without targeting them by secure IDs.

Pagination Parameters

info

All pagination parameters and their values are added to the URL as query parameters.

Pagination parameters include:

limit

An integer parameter that determines how many items are returned in the response. The entered value cannot exceed 1000.

The default value is 10, meaning that a maximum of ten items will be returned.

Example

limit=100: returns 100 items if their total number is more or equal to 100, or all the existing items if their quantity is less than 100.

order

A string parameter that allows to sort the returned objects. Three values are accepted for this parameter:

attribute name + asc to sort the items in the response in the ascending or alphabetical order (default order).
attribute name + desc to sort the items in the response in the descending or reverse-alphabetical order.
shuffle to randomize the order of the items in the response.

Example

order=name+desc: returns objects sorted by name in reverse-alphabetical order.
order=name (shorthand for order=name+asc): returns objects sorted by name in alphabetical order.
order=shuffle: returns objects in randomized order.

offset

An integer parameter that determines the amount of items that are skipped in the response.

The default value is 0, meaning that the first existing item will appear first.

Example

offset=2: if there are five records, the response will not include the first two records; instead, it will return records for items three through five.

note

The offset parameter is not used together with the after/ before arguments.

Example Request

This request returns Country objects sorting them descending by the common_name attritute, starting with the second record available, and returns a maximum of two records.

curl -X GET \
'https://api.carrierx.com/core/v2/countries?offset=2&limit=2&order=common_name+desc' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

To view records not included in the response, make a request to the URL value of the previous or the next key.

{
  "count": 2,
  "has_more": true,
  "items": [
    {
      "capital": "Sana'a",
      "common_name": "Yemen",
      "dialing_prefix": "967",
      "domain": "ye",
      "iso_3166_alpha_2": "YE",
      "iso_3166_alpha_3": "YEM",
      "iso_3166_numeric": 887,
      "mcc": "421",
      "official_name": "Republic of Yemen",
      "region": "Asia",
      "subregion": "Western Asia"
    },
    {
      "capital": "El Aaiún",
      "common_name": "Western Sahara",
      "dialing_prefix": null,
      "domain": "eh",
      "iso_3166_alpha_2": "EH",
      "iso_3166_alpha_3": "ESH",
      "iso_3166_numeric": 732,
      "mcc": null,
      "official_name": "Sahrawi Arab Democratic Republic",
      "region": "Africa",
      "subregion": "Northern Africa"
    }
  ],
  "limit": 2,
  "offset": 2,
  "pagination": {
    "next": "https://api.carrierx.com/core/v2/countries?limit=2&order=common_name+desc&offset=4",
    "previous": "https://api.carrierx.com/core/v2/countries?limit=2&order=common_name+desc&offset=0"
  },
  "total": 251
}

after/ before

For some objects (e.g., Call Detail Record or SMS Detail Record objects), the system will not return their total number. This can happen as the number dynamically changes in large quantities and can become not relevant by the time of the next request.

In this case, instead of using the standard pagination offset (which is rather difficult to calculate as the system does not return the total number of objects), you can use the after or before query arguments. With these arguments, the system will return the objects which precede or follow the entered object secure ID. This might be useful if you want to receive an exact range of the objects and know the secure IDs of the records which start and end this range.

Parameter	Data Type	Description
after	string	The secure ID of the object. The response will include only the results which follow the specified secure ID in the list of the object secure IDs.
before	string	The secure ID of the object. The response will include only the results which precede the specified secure ID in the list of object secure IDs.

note

If you use the after or before query arguments:

the response pagination attribute will also include the secure IDs of the previous or next objects instead of the offset value;
you cannot set the offset to any value except 0 (normally, you should omit the offset query attribute from such requests);
you can only apply the sorting by the limited number of the object attributes (e.g., date_stop for Call Detail Record objects or date_insert for SMS Detail Record objects).

Currently, CarrierX supports the pagination that uses the after and before arguments for the following objects and methods:

Object	Method	Sorting ('order') Values
Call Detail Record	Get Call Detail Records method	`date_stop`
SMS Detail Record	Get Message Detail Records method	`date_insert`

tip

Refer to our Call Detail Record Application Quick Start to learn more about how you can use the after and before pagination query arguments.

Example Request

This request returns a maximum of one record of SMS Detail Record objects following the object with the b6d574ea-b11f-41fd-a25f-602e7b28807f secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/sms/message_drs?after=b6d574ea-b11f-41fd-a25f-602e7b28807f&limit=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

To view records not included in the response, make a request to the URL value of the previous key.

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "date_insert": "2025-07-24T10:25:11.000Z",
            "date_sent": "2025-07-24T10:25:11.014Z",
            "date_start": "2025-07-24T10:25:11.014Z",
            "date_stop": "2025-07-24T10:25:12.014Z",
            "delay_sent": 0,
            "direction": "outbound",
            "dr_sid": "92cd9154-2f53-4e62-8b4e-8ff6e4849d16",
            "mcc": 310,
            "media_urls": [],
            "message": "This is a test message.",
            "message_segments": 1,
            "mnc": 999,
            "number_billing": "15162065870",
            "number_dst": "12078152557",
            "number_external": "12078152557",
            "number_src": "15162065870",
            "partner_sid": "8d180104-0b34-4e55-907f-4a72409484c9",
            "price": "0.005",
            "provider": "tsg",
            "rate": "0.005",
            "status": "sent",
            "type": "sms",
            "user_data": "test_message",
            "version": null
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "previous": "https://api.carrierx.com/core/v2/sms/message_drs?before=92cd9154-2f53-4e62-8b4e-8ff6e4849d16&limit=1&offset=0"
    },
    "total": null
}

Request Parameters Combinations

You can use the following combinations of the pagination parameters:

limit, offset, order: https://api.carrierx.com/core/v2/countries?limit=2&offset=2&order=common_name+desc
after, limit, order: https://api.carrierx.com/core/v2/calls/call_drs?after=bb2aacd2-23d3-418e-9ec0-2fc45c5f9d76&limit=1&order=date_stop+asc
before, limit, order: https://api.carrierx.com/core/v2/calls/call_drs?before=56fb6b94-811e-4952-b242-4e06f4e95b7e&limit=1&order=date_stop+desc
after, before, limit, order: https://api.carrierx.com/core/v2/sms/message_drs?after=012e1d6a-75ac-43ec-bacc-68f1ef1c60a3&before=b6d574ea-b11f-41fd-a25f-602e7b28807f&limit=100&order=date_insert+desc

If you omit any of the parameters from the response, their default values will be used (if there are any).

Pagination Response

The JSON response for a successful query using the pagination parameters will include the following attributes:

Attribute	Data Type	Description
count	integer	The number of `items` present in the response.
has_more	boolean	Whether or not there are more records existing outside of the queried parameters (e.g., if the number of `items` that exist exceeds the `limit` value, the `has_more` value in the response will be set to `true`).
items	array of objects	The list of the objects which match the request with the pagination query parameters applied.
limit	integer	The limit value applied to the request.
offset	integer	The offset value applied to the request.
pagination	object	The links that allow getting the objects which precede or follow the objects in the response due to the offset or after/ before arguments used in the request. This attribute will be an empty object if there are no more records existing outside of the queried parameters. If there are existing records outside of the query, the pagination value will include the `next` or `previous` URLs, or both of them.
total	integer	The total number of the queried objects that match the search criteria. This value will be set to `null` with the uncountable objects (call detail records, messages, etc.)

tip

You can use the URLs present in the response pagination attribute to obtain the remainder of the records available without modifying the original query. Simply construct another GET request with the URL(s) provided in this field.

note

You can additionally restrict the results returned in the response using Result Filtering and/or Field Filtering.

Pagination Parameters​

limit​

order​

offset​

Example Request​

after/ before​

Example Request​

Request Parameters Combinations​

Pagination Response​

Pagination Parameters

limit

order

offset

Example Request

after/ before

Example Request

Request Parameters Combinations

Pagination Response