Paging

Overview

Most of RealTheory's APIs support paging, which allows large result sets to be retrieved in smaller, manageable batches rather than in a single response. Paging is especially important for large environments and fleets, where the number of records, such as Pods or other short-lived objects, can be significant.

Because all RealTheory APIs follow a similar paging pattern, once you understand how to page through one endpoint, you can apply the same approach to any other.

Paging Parameters

APIs that support paging accept the following query string parameters:

{index} - is the starting index of the records to include in the response. This parameter is optional and defaults to 0 if not specified.
{count} - is the maximum number of records to return. This parameter is optional and defaults to 100 if not specified. Most APIs support a maximum {count} of up to 500, but this can vary between APIs, so you should check each API to verify its supported maximum.
{order} - is a string containing the name of the attribute to sort on. This parameter is optional.
{direction} - is a number that controls the direction of the sort. A value equal to or greater than 0 indicates ascending order; a value less than 0 indicates descending order. This parameter is optional and defaults to 0 if not specified.

For example, the SystemAlert endpoint exposes these parameters as shown below:

GET <endpoint>/theory/api/v1/alert/systemalerts/search/query/{query}?index={index}&count={count}&order={order}&direction={direction}

Note: All calls to RealTheory APIs must be authenticated and authorized. See Authentication for more details.

Paging Through All Records

To retrieve a complete result set, call the API repeatedly, incrementing the {index} by the value of {count} on each call, until a response returns fewer records than the {count} requested. A response containing fewer records than requested indicates that the end of the result set has been reached.

For example, to page through results 100 records at a time:

GET <endpoint>/theory/api/v1/alert/systemalerts/search/query/{query}?index=0&count=100&order=level&direction=1
GET <endpoint>/theory/api/v1/alert/systemalerts/search/query/{query}?index=100&count=100&order=level&direction=1
GET <endpoint>/theory/api/v1/alert/systemalerts/search/query/{query}?index=200&count=100&order=level&direction=1
...

The first call returns records 0–99, the second returns records 100–199, the third returns records 200–299, and so on. Continue incrementing the {index} by {count} until a call returns fewer than 100 records, at which point all available records have been retrieved.

Note: It is strongly recommended that a consistent {order} and {direction} be used across all calls in a paging sequence. This ensures records are returned in a stable order and avoids records being skipped or duplicated between pages.

The x-total-count Header

Responses from paged APIs include an x-total-count header, which provides a count of the total number of available records at the time the request was made.

While the x-total-count header can be useful for displaying an approximate total, it is not the recommended way to determine when all records have been retrieved in large environments or fleets. In these environments, the number of records can change between calls as dynamic objects, such as Pods or other short-lived resources, are created and destroyed. Relying on the x-total-count header to drive paging can therefore result in records being skipped or in unnecessary additional calls.

The preferred and most reliable approach is to keep paging until a response returns fewer records than the {count} requested, as described above.

Summary

To page through all records returned by a RealTheory API:

Start with an {index} of 0 and a fixed {count} (for example, 100).
Use a consistent {order} and {direction} across all calls.
Increment the {index} by the {count} on each subsequent call.
Stop when a call returns fewer records than the {count} requested.