Samsara Developer Portal

Integrate your data with the Samsara API, customize the Samsara experience, and join a community of developers building with Samsara.

Get Started

Pagination

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 <<token>>'
{
  "data": [ ... ],
  "pagination": {
    "endCursor": "abcdefg",
    "hasNextPage": true
  }
}
  1. 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.
curl --request GET 'https://api.samsara.com/fleet/vehicles?after=abcdefg' \
--header 'Authorization: Bearer <<token>>'
{
  "data": [ ... ],
  "pagination": {
    "endCursor": "hijklmnop",
    "hasNextPage": true
  }
}
  1. Continue using the above pattern until hasNextPage is false.

Sample Code

import requests

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

hasNextPage = True
while hasNextPage:
    response = requests.request("GET", url, headers=headers, params=params).json()
    for vehicle in response["data"]:
        # process each vehicle
    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.

Updated 2 months ago


Pagination


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.