Pagination

Most LIST endpoints that return a set of objects will include keyset pagination support. This will allow you to traverse linearly forward and backwards in a result set.

Pagination uses two URL parameters, limit and cursor. The limit parameter will specify the size of the result set, or cursor page size, that will be returned. The cursor parameter will specify which page of result set.

For example, to start reading all time punches you would start with this request to the LIST /time_punches. By specifying limit=20, the result set will be limited to 20 time punches.

curl --request GET --url 'https://api.7shifts.com/v2/company/1234/time_punches?limit=20' \
--header 'Authorization: Bearer ISSUED_TOKEN' \
--header 'x-api-version: 2022-05-01' \
--header 'x-company-guid: GUID'

The resulting payload will include the first 20 punches that match the search criteria and a meta attribute including the cursor data.

{
    "data": [
        {...
        }
    ],
    "meta": {
        "cursor": {
            "current": "eyJpZCI6Ijg1Njg1NjYwIiwibmV4dCI6dHJ1ZX0=",
            "prev": "eyJpZCI6Ijg1NzgxNzY4IiwibmV4dCI6ZmFsc2V9",
            "next": "eyJpZCI6Ijg2MDIzMDM2IiwibmV4dCI6dHJ1ZX0=",
            "count": 20
        }
    },
    "object": "time_punches"
}

Here’s an explanation of the fields of meta payload:

Parameter	Type	Description
current	string	The current cursor for the returned result set
prev	string	The previous cursor to navigate to the previous page. If this is the first result set the prev cursor will be `null`
next	string	The previous cursor to navigate to the next page. If this is the last page the next cursor will be `null`
count	integer	The total items in the current cursor.

To retrieve the next set of results, pass the cursor parameter with the next cursor value.

curl --request GET --url 'ttps://api.7shifts.com/v2/company/1234/time_punches?cursor=eyJpZCI6Ijg2MDIzMDM2IiwibmV4dCI6dHJ1ZX0=' \
--header 'Authorization: Bearer ISSUED_TOKEN' \
--header 'x-api-version: 2022-05-01' \
--header 'x-company-guid: GUID'

The default for limit is 20 and a maximum of 200 on most endpoint unless otherwise stated in the endpoint definition.

You would stop paginating results until the next cursor value is null