Pagination

Iterate through paginated list endpoints using cursor-based pagination with the endCursor and hasNextPage fields.

Overview

Endpoints that GET a list of objects are paginated. This means that every time you make a request, you’ll receive one “page” of results and an endCursor to retrieve the next page:

Call Sequence	Description
Call #1	GET /fleet/vehicles First page of data endCursor: abcdefg hasNextPage: true
Call #2	GET /fleet/vehicles?after=abcdefg Second page of data endCursor: hijklmnop hasNextPage: true
Call #3	GET /fleet/vehicles?after=hijklmnop Third page of data endCursor: qrstuvwxyz hasNextPage: false

To work with paginated endpoints, do the following:

1. Submit the first request

   You may omit the after parameter or provide an empty string.

   curl --request GET 'https://api.samsara.com/fleet/vehicles?after=' \
   --header 'Authorization: Bearer YOUR_API_TOKEN'
   

   {
     "data": [ ],
     "pagination": {
       "endCursor": "abcdefg",
       "hasNextPage": true
     }
   }
   
2. Use the endCursor for subsequent requests

   If hasNextPage is true, use the endCursor to request the next page of data by providing it as the after parameter in your subsequent request. Continue to use any additional parameters you had passed in the 1st request.

   curl --request GET 'https://api.samsara.com/fleet/vehicles?after=abcdefg' \
   --header 'Authorization: Bearer YOUR_API_TOKEN'
   

   {
     "data": [ ],
     "pagination": {
       "endCursor": "hijklmnop",
       "hasNextPage": true
     }
   }
   
3. Continue until hasNextPage is false

   Continue using the above pattern until hasNextPage is false.

Sample Code

import requests

url = "https://api.samsara.com/fleet/vehicles"
params = {}
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN"
}

hasNextPage = True
while hasNextPage:
    response = requests.request("GET", url, headers=headers, params=params).json()
    for vehicle in response["data"]:
        # process each vehicle
        pass
    hasNextPage = response["pagination"]["hasNextPage"]
    params["after"] = response["pagination"]["endCursor"]

Some endpoints on the legacy API use slightly different parameter and field names for pagination.

The limit Parameter

Some API endpoints support an optional limit query parameter. This parameter allows you to limit the number of objects returned on each page. The default and max for this value is 512.

If the endpoint does not support a limit parameter, then Samsara tunes the number of results on each page in order to optimize performance and may change the number of results on each page at any time.

Cursor Expiration

Cursors expire after 30 days.

Real-time Data

Some API endpoints allow you to follow a feed of real-time data. These endpoints utilize pagination. Each time you make a request to one of the /feed endpoints with a cursor, you will receive all of the updates to the data since that cursor.

If hasNextPage is false, it is recommended that you wait at least 5 seconds before making another request to retrieve new data.

You can see an example of following real-time data in the Telematics Sync guide.

Short or Empty Pages

Sometimes a page might have very few results or might be empty but hasNextPage may still be true.

This behavior is due to how Samsara collects and stores data. Sometimes drivers, vehicles, or other objects will be inactive or will not have produced new data since the last time a request was made. In these cases, that object is omitted from the page of that response. However, objects on subsequent pages may still have updates.

It is important that you always keep paginating if hasNextPage is true. This will allow you to collect all the available data.