APIs CMO API Understanding Pagination

This page explains how pagination works in the Connection Management Orchestrator (CMO) API for product list requests.

Pagination in CMO is slightly different from a regular single-database pagination model because the CMO API can retrieve products from one or more external platforms, and each platform can have one or more credentials/accounts configured for the same tenant.

Pagination parameters

The following query parameters are used for paginated product list requests:

Parameter	Required	Type	Minimum	Maximum	Description
`pageSize`	Yes	Integer	`1`	`1000`	Maximum number of products requested by the client for the response page.
`pageNumber`	Yes	Integer	`1`	`10000000`	Page number requested by the client.

Example:

GET /{tenant}/product?pageSize=10&pageNumber=1

NOTE

Both pageSize and pageNumber must be positive integers.

If either value is missing, lower than 1, not an integer, or higher than the configured maximum, the CMO returns a validation error.

Why the CMO service adjusts the requested page size

CMO does not always send the client-provided pageSize directly to each external platform through its adapter services.

Because a tenant can have credentials for multiple platforms, or multiple credentials for the same platform, CMO first calculates how many configured accounts may be queried for the request.

CMO then divides the requested pageSize across those accounts.

This is done to avoid returning too many products when several platform accounts are involved.

For example, if the client requests:

GET /TENANT/product?pageSize=10&pageNumber=1

and the tenant has 2 matching platform accounts, CMO requests up to 5 products from each account:

requested pageSize = 10
matching accounts = 2
effective page size per account = floor(10 / 2) = 5

The final response can contain up to 10 products in total.

How CMO counts matching accounts

For pagination purposes, CMO counts credentials/accounts, not only platform names.

This distinction is important.

A tenant may have:

one credential for one platform
multiple credentials for the same platform
credentials across several different platforms
filters that limit the request to only some platforms or account names

Each matching credential/account contributes to the pagination calculation.

General formula

effective page size per account = floor(requested pageSize / matching account count)

If the requested pageSize is smaller than the number of matching accounts, CMO sends pageSize = 1 to each matching account and then trims the aggregated result to the originally requested pageSize. In this scenario the CMO also returns a 400 “Bad Request” error in the response indicating that all items couldn’t be retrieved because of the small pageSize param sent (see in examples bellow).

if requested pageSize < matching account count: 
  effective page size per account = 1 
else: 
  effective page size per account = floor(requested pageSize / matching account count)

The pageNumber is passed to each matching account unchanged.

Important behavior with multiple credentials

CMO counts the number of matching credentials/accounts, even when several credentials belong to the same external platform.

For example, if a tenant has 3 credentials for INTELSAT, CMO treats this as 3 accounts for pagination purposes.

Platform: INTELSAT 
Credentials/accounts: 3
matching account count = 3

So, if the client requests:

GET /TENANT/product?pageSize=30&pageNumber=1&platform=INTELSAT

CMO calculates:

requested pageSize = 30 
matching accounts = 3
effective page size per account = floor(30 / 3) = 10

CMO sends a request similar to this to each INTELSAT account:

{ 
  "pageSize": 10, 
  "pageNumber": 1 
}

The final response can contain up to 30 products in total.

Response pagination headers

The CMO API returns pagination information through the HTTP Link response header. There are no separate pagination metadata headers such as X-Total-Count or Total-Count.

When a paginated list of products is returned, the CMO sets the response status to 206 Partial Content.

The Link header

The Link header contains navigation links to the current, first, next, and previous pages. It follows the format:

Link: <...>;rel="self",<...>;rel="first",<...>;rel="next",<...>;rel="prev"

The following relations are included:

rel="self": The current requested page.
rel="first": The first page with the same page size.
rel="next": The next page. This is only included if the current page number is less than the configured maximum page number.
rel="prev": The previous page. This is only included if the current page number is greater than 1.

Example

If the client calls: GET /someTenant/product?pageNumber=2&pageSize=25

The response includes:

HTTP/1.1 206 Partial Content
Link: <https://host/someTenant/product?pageNumber=2&pageSize=25>;rel="self",<https://host/someTenant/product?pageNumber=1&pageSize=25>;rel="first",<https://host/someTenant/product?pageNumber=3&pageSize=25>;rel="next",<https://host/someTenant/product?pageNumber=1&pageSize=25>;rel="prev"

Examples

Example 1: One platform with one credential

Tenant configuration:

Platform	Credentials/accounts
INTELSAT	1

Request:

GET /TENANT/product?pageSize=10&pageNumber=1&platform=INTELSAT

Calculation:

requested pageSize = 10 
matching accounts = 1
effective page size per account = floor(10 / 1) = 10

CMO sends to the platform:

{ 
  "pageSize": 10, 
  "pageNumber": 1 
}

Expected response behavior:

CMO returns up to 10 products.

Example response:

{
  "entities": [
    {
      "id": "INTELSAT-27492",
      "href": "https://qa.spacegate.telekom.de/.../product/INTELSAT-27492",
      "status": "TERMINATED",
      "connectivityType": "SATELLITE",
      "productCharacteristic": [
        {
          "name": "PLATFORM",
          "value": "INTELSAT"
        }
      ],
      "relatedParty": [
        {
          "name": "DT_API_3",
          "characteristic": [
            {
              "name": "PLATFORM_ACCOUNT",
              "value": "723"
            }
          ],
          "role": "customer"
        }
      ],
      ...
      "@type": "IoTConnection"
    },
    {
      "id": "INTELSAT-27493",
      ...
      "@type": "IoTConnection"
    }
  ],
  "errors": [],
  "correlationId": "e0279937-1d69-45a5-ab38-91aba1f322dc"
}

Example 2: One platform with multiple credentials

Tenant configuration:

Platform	Credentials/accounts
INTELSAT	3

Request:

GET /TENANT/product?pageSize=12&pageNumber=1&platform=INTELSAT

Calculation:

requested pageSize = 12 
matching accounts = 3
effective page size per account = floor(12 / 3) = 4

CMO sends one request per credential/account:

{ 
  "pageSize": 4, 
  "pageNumber": 1 
}

Expected response behavior:

CMO may return up to 12 products in total:
up to 4 from INTELSAT account 1
up to 4 from INTELSAT account 2
up to 4 from INTELSAT account 3

Example response:

{
  "entities": [
    {
      "id": "INTELSAT-27492",
      "href": "https://qa.spacegate.telekom.de/.../product/INTELSAT-27492",
      "status": "TERMINATED",
      "connectivityType": "SATELLITE",
      "productCharacteristic": [
        {
          "name": "PLATFORM",
          "value": "INTELSAT"
        }
      ],
      "relatedParty": [
        {
          "name": "DT_API_3",
          "characteristic": [
            {
              "name": "PLATFORM_ACCOUNT",
              "value": "723"
            }
          ],
          "role": "customer"
        }
      ],
      ...
      "@type": "IoTConnection"
    },
    {
      "id": "INTELSAT-27493",
      "relatedParty": [
        {
          "name": "DT_API_4",
          "characteristic": [
            {
              "name": "PLATFORM_ACCOUNT",
              "value": "724"
            }
          ],
          "role": "customer"
        }
      ],
      ...
      "@type": "IoTConnection"
    },
    {
      "id": "INTELSAT-27494",
      "relatedParty": [
        {
          "name": "DT_API_5",
          "characteristic": [
            {
              "name": "PLATFORM_ACCOUNT",
              "value": "725"
            }
          ],
          "role": "customer"
        }
      ],
      ...
      "@type": "IoTConnection"
    }
  ],
  "errors": [],
  "correlationId": "e0279937-1d69-45a5-ab38-91aba1f322dc"
}

NOTE

The response may contain fewer products than the requested pageSize if one or more external platform accounts return fewer products.

Example 3: Multiple platforms with one credential each

Tenant configuration:

Platform	Credentials/accounts
AIRLINQ	1
TMSP	1
IOTA	1

Request:

GET /TENANT/product?pageSize=30&pageNumber=1

Calculation:

requested pageSize = 30 
matching accounts = 3
effective page size per account = floor(30 / 3) = 10

CMO sends the following pagination payload to each matching platform account:

{ 
  "pageSize": 10, 
  "pageNumber": 1 
}

Expected response behavior:

CMO may return up to 30 products in total:
up to 10 from AIRLINQ
up to 10 from TMSP
up to 10 from IOTA

Example response:

{
  "entities": [
    {
      "id": "AIRLINQ-8991864040706976944",
      "href": "https://qa.spacegate.telekom.de/.../product/AIRLINQ-8991864040706976944",
      "status": "CREATED",
      "connectivityType": "CELLULAR",
      "productCharacteristic": [
        {
          "name": "PLATFORM",
          "value": "AIRLINQ"
        }
      ],
      "relatedParty": [
        {
          "name": "AIRLINQ_1",
          "characteristic": [
            {
              "name": "PLATFORM_ACCOUNT",
              "value": "631"
            }
          ],
          "role": "customer"
        }
      ],
      ...
      "@type": "IoTConnection"
    },
    {
      "id": "TMSP-8949020160005183930",
      "href": "https://qa.spacegate.telekom.de/.../product/TMSP-8949020160005183930",
      "status": "SUSPENDED",
      "connectivityType": "CELLULAR",
      "productCharacteristic": [
        {
          "name": "PLATFORM",
          "value": "TMSP"
        }
      ],
      "relatedParty": [
        {
          "name": "Ref 93541",
          "characteristic": [
            {
              "name": "PLATFORM_ACCOUNT",
              "value": "93541"
            }
          ],
          "role": "customer"
        }
      ],
      ...
      "@type": "IoTConnection"
    },
    {
      "id": "IOTA-123456789",
      "status": "ACTIVE",
      "relatedParty": [
        {
          "name": "IOTA_1",
          "characteristic": [
            {
              "name": "PLATFORM_ACCOUNT",
              "value": "IOTA_ACC_1"
            }
          ],
          "role": "customer"
        }
      ],
      ...
      "@type": "IoTConnection"
    }
  ],
  "errors": [],
  "correlationId": "e0279937-1d69-45a5-ab38-91aba1f322dc"
}

Example 4: Multiple credentials, but the platform filter selects only one platform

Tenant configuration:

Platform	Credentials/accounts
AIRLINQ	2
TMSP	4
IOTA	1

Request:

GET /TENANT/product?pageSize=20&pageNumber=1&platform=AIRLINQ

Only AIRLINQ credentials are included in the calculation.

Calculation:

requested pageSize = 20 
matching platform = AIRLINQ 
matching accounts = 2
effective page size per account = floor(20 / 2) = 10

CMO sends the following to each AIRLINQ account:

{ 
  "pageSize": 10, 
  "pageNumber": 1 
}

Expected response behavior:

CMO may return up to 20 AIRLINQ products in total. Products from TMSP and IOTA are not requested because the platform filter limits the scope to AIRLINQ.

Example response:

{
  "entities": [
    {
      "id": "AIRLINQ-8991864040706976944",
      "href": "https://qa.spacegate.telekom.de/.../product/AIRLINQ-8991864040706976944",
      "status": "CREATED",
      "relatedParty": [
        {
          "name": "AIRLINQ_1",
          "characteristic": [
            {
              "name": "PLATFORM_ACCOUNT",
              "value": "631"
            }
          ],
          "role": "customer"
        }
      ],
      ...
      "@type": "IoTConnection"
    },
    {
      "id": "AIRLINQ-8991864040706976945",
      "relatedParty": [
        {
          "name": "AIRLINQ_2",
          "characteristic": [
            {
              "name": "PLATFORM_ACCOUNT",
              "value": "632"
            }
          ],
          "role": "customer"
        }
      ],
      ...
      "@type": "IoTConnection"
    }
  ],
  "errors": [],
  "correlationId": "e0279937-1d69-45a5-ab38-91aba1f322dc"
}

Example 5: Multiple credentials, most belonging to another platform

Tenant configuration:

Platform	Credentials/accounts
AIRLINQ	1
TMSP	5
IOTA	1

Request:

GET /TENANT/product?pageSize=12&pageNumber=1&platform=AIRLINQ

Even though the tenant has 7 credentials in total, only the matching AIRLINQ credential is counted.

Calculation:

requested pageSize = 12 
matching platform = AIRLINQ 
matching accounts = 1
effective page size per account = floor(12 / 1) = 12

Expected response behavior:

CMO sends pageSize = 12 to the AIRLINQ account. TMSP and IOTA credentials are not included in the calculation because they do not match the platform filter.

Example response:

{
  "entities": [
    {
      "id": "AIRLINQ-8991864040706976944",
      "href": "https://qa.spacegate.telekom.de/.../product/AIRLINQ-8991864040706976944",
      "status": "CREATED",
      "relatedParty": [
        {
          "name": "AIRLINQ_1",
          "characteristic": [
            {
              "name": "PLATFORM_ACCOUNT",
              "value": "631"
            }
          ],
          "role": "customer"
        }
      ],
      ...
      "@type": "IoTConnection"
    }
  ],
  "errors": [],
  "correlationId": "e0279937-1d69-45a5-ab38-91aba1f322dc"
}

Example 6: Requested page size is smaller than the number of matching accounts

Tenant configuration:

Platform	Credentials/accounts
AIRLINQ	2
TMSP	2
IOTA	2

Total matching accounts:

matching accounts = 6

Request:

GET /TENANT/product?pageSize=3&pageNumber=1

Calculation:

requested pageSize = 3 
matching accounts = 6
requested pageSize is smaller than matching accounts 
effective page size per account = 1

CMO sends the following to each matching account:

{ 
  "pageSize": 1, 
  "pageNumber": 1 
}

Because 6 accounts may each return 1 product, the aggregated result could contain more products than the requested pageSize.

In this case, CMO trims the response to the requested pageSize.

Expected response behavior:

CMO returns only 3 products. CMO also includes a warning problem explaining that not all items could be retrieved because pageSize is smaller than the number of configured accounts.

Example response:

{
  "entities": [
    {
      "id": "AIRLINQ-8991864040706976944",
      "href": "https://qa.spacegate.telekom.de/.../product/AIRLINQ-8991864040706976944",
      "status": "CREATED",
      "relatedParty": [
        {
          "name": "AIRLINQ_1",
          "characteristic": [
            {
              "name": "PLATFORM_ACCOUNT",
              "value": "631"
            }
          ],
          "role": "customer"
        }
      ],
      ...
      "@type": "IoTConnection"
    },
    {
      "id": "TMSP-8949020160005183930",
      "relatedParty": [
        {
          "name": "Ref 93541",
          "characteristic": [
            {
              "name": "PLATFORM_ACCOUNT",
              "value": "93541"
            }
          ],
          "role": "customer"
        }
      ],
      ...
      "@type": "IoTConnection"
    },
    {
      "id": "AIRLINQ-8991864040706976945",
      "relatedParty": [
        {
          "name": "AIRLINQ_2",
          "characteristic": [
            {
              "name": "PLATFORM_ACCOUNT",
              "value": "632"
            }
          ],
          "role": "customer"
        }
      ],
      ...
      "@type": "IoTConnection"
    }
  ],
  "errors": [
    {
      "type": "Bad Request",
      "status": 400,
      "title": "Small page size",
      "detail": "Not all items could be retrieved because requested pageSize less than a number of configured accounts: 6",
      "externalErrors": [],
      "relatedParty": [],
      "@type": "problem"
    }
  ],
  "correlationId": "e0279937-1d69-45a5-ab38-91aba1f322dc"
}

NOTE

To avoid this warning, request a pageSize that is greater than or equal to the number of matching credentials/accounts.

The relatedParty.name filter can also affect the account count used for pagination.

When a request includes a related party name filter, CMO tries to count only credentials/accounts matching that account name.

Example tenant configuration:

Platform	Account name	Credentials/accounts
AIRLINQ	`account-a`	1
AIRLINQ	`account-b`	1
TMSP	`account-c`	1

Request:

GET /TENANT/product?pageSize=10&pageNumber=1&relatedParty.name=account-a

Calculation:

requested pageSize = 10 
matching related party account = account-a 
matching accounts = 1
effective page size per account = floor(10 / 1) = 10

Expected response behavior:

CMO sends pageSize = 10 only for the matching account.

If both a platform filter and a related party filter are provided, CMO calculates the matching accounts based on the combined scope of the request.

Page number behavior

The requested pageNumber is sent unchanged to each matching platform account.

For example:

GET /TENANT/product?pageSize=20&pageNumber=3

If there are 4 matching accounts:

requested pageSize = 20 
requested pageNumber = 3 
matching accounts = 4
effective page size per account = floor(20 / 4) = 5

CMO sends to each account:

{ 
  "pageSize": 5, 
  "pageNumber": 3 
}

Expected response behavior:

CMO returns the aggregated results from page 3 of each matching account.

Summary

CMO pagination is based on the number of matching credentials/accounts.

matching accounts = credentials/accounts selected by tenant configuration and request filters
effective page size per account = floor(requested pageSize / matching accounts)

Important points:

pageSize and pageNumber are mandatory pagination parameters.
Both must be positive integers.
For product list requests, pageSize must be between 1 and 1000, while pageNumber must be between 1 and 10,000,000.
Pagination navigation is provided via the HTTP Link response header.
The response status for paginated product list requests is 206 Partial Content.
CMO counts credentials/accounts, not only platform names.
Multiple credentials for the same platform are counted separately.
Platform filters reduce the set of matching accounts.
Related party filters can reduce the set of matching accounts.
pageNumber is sent unchanged to each matching account.
If pageSize is smaller than the number of matching accounts, CMO requests one item per account and trims the final response.

APIs CMO API Understanding Pagination

Pagination parameters Copied!

Why the CMO service adjusts the requested page size Copied!

How CMO counts matching accounts Copied!

General formula Copied!

Important behavior with multiple credentials Copied!

Response pagination headers Copied!

The Link header Copied!

Examples Copied!

Example 1: One platform with one credential Copied!

Example 2: One platform with multiple credentials Copied!

Example 3: Multiple platforms with one credential each Copied!

Example 4: Multiple credentials, but the platform filter selects only one platform Copied!

Example 5: Multiple credentials, most belonging to another platform Copied!

Example 6: Requested page size is smaller than the number of matching accounts Copied!

Filtering by related party name Copied!

Page number behavior Copied!

Summary Copied!

Pagination parameters

Why the CMO service adjusts the requested page size

How CMO counts matching accounts

General formula

Important behavior with multiple credentials

Response pagination headers

The Link header

Examples

Example 1: One platform with one credential

Example 2: One platform with multiple credentials

Example 3: Multiple platforms with one credential each

Example 4: Multiple credentials, but the platform filter selects only one platform

Example 5: Multiple credentials, most belonging to another platform

Example 6: Requested page size is smaller than the number of matching accounts

Filtering by related party name

Page number behavior

Summary