Skip to main content

Pagination and sorting

Pass an explicit sort when you list resources. Many list endpoints load and shape matching data before applying ordering and pagination, and the default ordering may not be stable.

Note: Balancer is in beta. Endpoints, fields and behavior may change before general availability, and the feature must be enabled on your account before use. Contact your NetActuate account manager to request access.

Offset-based lists​

ParameterDefaultConstraints and behavior
limit100Integer from 1 to 1000.
offset0Integer at least 0.
orderascendingascending or descending.
orderByOften createdOnMust name a supported returned key. The shared sorter checks the first returned row.
searchNo search suppliedMaximum 255 characters; case-insensitive substring search in the shared list helper.
filtersNo filters suppliedDecoded JSON interpreted by the list comparator. Supported fields depend on the operation.

The shared list helper loads matching rows, shapes them, applies search and filters, sorts, then slices the requested page. data.meta.total counts the filtered rows before slicing. data.meta.offset and data.meta.limit describe the page. data.data contains the page array; metadata can also include suggestedFilters.

A declared default such as createdOn may no longer exist after response shaping. In that case, ordering can remain the underlying fetch order. No stable secondary sort is added. Pass an explicit supported key, preferably a unique identifier, instead of relying on the default. Changes between requests can still affect offset-based traversal.

Read an explicit page​

Use an account API key and set BALANCER_API_BASE to https://<your-api-host>, using the host shown in the Balancer portal.

  1. List HTTP load balancers in identifier order.

    curl --silent --show-error --get "$BALANCER_API_BASE/http-loadbalancers" \
      -H "x-api-key: $BALANCER_API_KEY" \
      --data-urlencode 'limit=100' --data-urlencode 'offset=0' \
      --data-urlencode 'orderBy=httpLbId' --data-urlencode 'order=ascending'

    Expect HTTP 200 with data.meta and data.data. Verify that identifiers increase and that metadata reports your requested offset and limit.

  2. Request the next page. Keep the same sort, search and filters.

    curl --silent --show-error --get "$BALANCER_API_BASE/http-loadbalancers" \
      -H "x-api-key: $BALANCER_API_KEY" \
      --data-urlencode 'limit=100' --data-urlencode 'offset=100' \
      --data-urlencode 'orderBy=httpLbId' --data-urlencode 'order=ascending'

    Expect HTTP 200 with the same envelope and an offset of 100. Compare identifiers with the previous page.

Exceptions​

Not every array is paginated. GET /auth/contexts returns complete account and organization arrays, sorted by name and then identifier within each array. GET /user/api-keys returns the complete key metadata array, ordered by creation time and then identifier. Check the operation before sending pagination arguments.