Pagination Query Parameters

The page_size and page_number query parameters divide large data sets into smaller sections to facilitate the handling of JSON responses and drive pagination in the user interface.

  • page_size — Defines a limit to the number of records returned in the API response body. The query parameter accepts an integer value. The default value and maximum allowed value is specific to the API used.

  • page_number — Defines which set of records to return when the number of records exceeds the value defined by the page size query parameter. The query parameter accepts an integer value. The default value for page_number is 1 which returns the first set of records. Additional pages can be retrieved in subsequent API call by defining a different page number.

For example, the following query for billing accounts includes the query parameter for page_size to return no more than 50 records and the query parameter for page_number to return the second set of 50 records:

GET https://example-gotransverse.com/billing/2/billing-accounts?page_size=50&page_number=2

The page size value does not apply to collections of objects within a record. By default, collections are limited to 50 objects. A more specific endpoint is often available to retrieve all objects related to a record.

For example, when querying for services using the /services endpoint, a service entity can include a collection of up to 50 service resource IDs associated with the service. You can then use the /services/{service_id}/service-resources endpoint to retrieve all service resource IDs for the specified service ID.

Query Response Header

A query will return a response header that includes information about the number of records and pages based on the page size and page number values:

  • x-element-count — The number of records returned in the response body.

  • x-total-count — The number of records matching the query parameters.

  • x-total-pages — The number of pages available to return relative to the page size query parameter.

For example, the following response header returned for a query for billing accounts found 450 records that match the submitted query parameters, returned 50 records in the response body, and has 9 pages of records available:

Copy
Example Query Response Header
 content-encoding: gzip 
 content-type: application/json 
 date: Wed23 Oct 2024 19:04:27 GMT 
 strict-transport-security: max-age=31536000; includeSubDomains 
 vary: Accept-Encoding 
 x-element-count: 50 
 x-total-count: 450 
 x-total-pages: 9 

When the omit_total_count query parameter is set to TRUE, the x-total-count and x-total-pages fields are not included in the response header.

 

 

 

Topic Updated: 10/2024.