Pagination

Pagination¶

Most Sophos Central APIs that return multiple resources wrap them in a "page" object. This has the following fields:

Field	Type	Purpose
`pages`	object	Contains pagination related metadata
`items`	array of object	Contains the paged items
`errors`	object	Optional embedded error object

All APIs have a default page size of 50 items, and support a maximum page size. This limit varies between API endpoints.

There are two (slightly) different styles of paging supported by different APIs that affects how pages are requested and the pages metadata in the returned response.

Page by offset¶

When paging by offset, the client asks for the specific page of data they want, starting from Page 1. The query parameters that affect paging are:

Query Parameter	Type	Default	Meaning
`page`	Integer	1	The 1-based index of the page to fetch.
`pageSize`	Integer	50	The number of items on each page. API implementations generally impose a "max page size" — the allowed upper limit for this parameter.
`pageTotal`	Boolean	false	Whether to calculate the number of pages in the data set.

The pages field in the response will have the following sub-fields:

Field in `pages`	Type	Meaning
`current`	Integer	The 1-based page number being returned
`size`	Integer	Same as the `pageSize` query parameter passed in or its default value.
`total`	Integer	(Optional) The total number of pages that exist, if `pageTotal=true` was passed into the request.
`maxSize`	Integer	The maximum page size that can be requested.

All query parameters are optional. By default, if you don't specify a query parameter, the first page with up to 50 items on it is returned. The number of pages isn't returned.

Example¶

GET https://us-01.central.sophos.com/endpoint/v1/endpoints?page=2&pageSize=10&pageTotal=true

This returns a response with the following shape:

{
    "pages": {
        "current": 2,
        "size": 10,
        "maxSize": 100,
        "total": 12
    },
    "items": [
        // 10 endpoint objects
    ]
}

Page by key¶

When paging by key, the client asks for a page worth of data after a particular matching key. You can omit this key to fetch the first page. The query parameters are as follows:

Query Parameter	Type	Default	Meaning
`pageFromKey`	String	(empty)	The key of an item in an ordered view or dataset, from which to fetch one page of data. The item with that key will be the first item in those returned.
`pageSize`	Integer	50	The number of items on each page. API implementations generally impose a "max page size" -- the allowed upper limit for this parameter.
`pageTotal`	Boolean	false	Whether to calculate the number of pages in the data set.

The pages field in the response will have the following sub-fields:

Field in `pages`	Type	Meaning
`fromKey`	String	The key of the first item in the array of items returned
`nextKey`	String	The key to use as the value of the `pageFromKey` query parameter when fetching the next page of data. This field won't present if there are no more pages to fetch.
`size`	Integer	Same as the `pageSize` query parameter passed in or its default value.
`total`	Integer	(Optional) The total number of pages that exist, if `pageTotal=true` was passed into the request.
`maxSize`	Integer	The maximum page size that can be requested.

All query parameters are optional. By default, if you don't specify a query parameter, the first page with up to 50 items on it is returned. The number of pages isn't returned.

Example¶

GET https://us-01.central.sophos.com/endpoint/v1/endpoints?pageFromKey=3cc3deef&pageSize=50&pageTotal=true

This returns a response with the following shape:

{
    "pages": {
        "fromKey": "3cc3deef",
        "nextKey": "49bbba02",
        "size": 50,
        "maxSize": 100,
        "total": 12
    },
    "items": [
        // 50 endpoint objects, the first of
        // which has the paging key '3cc3deef'
    ]
}