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

Vehicle Stats

Get real-time or historical vehicle stat data (odometers, engine state, fuel levels, engine hours)

As part of our new set of APIs, Samsara has released three new endpoints for retrieving vehicle stats data:

  • List most recent vehicle stats
  • Follow a real-time feed of vehicle stats
  • Get historical vehicle stats

See below for descriptions of each of these scenarios.

Vehicle Stat Types

All of the endpoints for vehicle stats allow you to request a specific stat type (currently, only one stat type is supported per request):

  • engineStates: The state of the engine (Off, On, Idle).
  • fuelPercents: The engine fuel level in percentage points.
  • obdOdometerMeters: The odometer reading according to on-board diagnostics. If Samsara does not have diagnostic coverage for a particular vehicle, the value for this stat type will be omitted. In these cases, we recommend using gpsOdometerMeters.
  • gpsOdometerMeters: The odometer reading according to GPS calculations. This calculation is based off GPS distance traveled and a manual odometer offset for a given vehicle, specified by the user in Samsara's dashboard or through the odometerMeters field in the PATCH /fleet/vehicles/{id} endpoint. gpsOdometerMeters is equal to the manual offset plus the GPS distance traveled since the offset was set. The value for this stat type will be omitted if a manual offset is not provided for a given vehicle. A manual offset can only be provided when we do not have diagnostic coverage for a particular vehicle.
  • obdEngineSeconds: The cumulative number of seconds the engine has run according to on-board diagnostics.
  • gpsDistanceMeters: The distance the vehicle has traveled since the gateway was installed based on GPS calculations.

You can provide one of the above stat types through the types query parameter for each endpoint.

The query parameter is named the plural types in case we are able to support multiple stat types per query in the future. Currently, only one is supported.

List most recent vehicle stats

The GET /fleet/vehicles/stats endpoint allows you to list most recent vehicle stat data for a "snapshot" of data. You can use the tagIds or vehicleIds parameters to optionally filter by tags or vehicles.

curl -X GET \
  'https://api.samsara.com/fleet/vehicles/stats?types=engineStates' \
  -H 'Authorization: Bearer <token>'
{
    "data": [
        {
            "id": "123456789",
            "name": "Tommy the Tractor",
            "engineState": {
                "time": "2019-11-20T19:32:38Z",
                "value": "Off"
            }
        }
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

The response will contain a data array of the most recent vehicle stats for the requested stats type (optionally filtered by the tagIds or vehicleIds you supplied).

See the reference docs for more details about the different stat types.

If the stats of more than 512 vehicles are requested, the response will be paginated.

Empty or Short Pages

There is a chance you will see pages where hasNextPage == true, but the page has an empty data array or fewer than 512 vehicles in the array.

This is the result of vehicles whose stats are unknown. This is usually due to devices that have not been connected yet.

There may be more pages of vehicles with stats available. It is important that you always keep paginating while hasNextPage == true.

Follow a real-time feed of vehicle stats

The GET /fleet/vehicles/stats/feed endpoint allows you to follow a real-time feed of vehicle stat data, optionally filtered by tags or vehicles.

Calling this endpoint with a given endCursor will provide all updates to location data generated after that endCursor.

Calling this endpoint without a given endCursor will provide the most recent locations for the requested vehicles, and an initial endCursor for subsequent calls.

This pattern is specifically designed to ensure that you will eventually receive all data regardless of connectivity issues. Even if your data stream is momentarily interrupted, once connectivity is restored, your endCursor will tell us what the last event you received was, and any updates since then will be sent in your subsequent request.

Here's an example:

Initial call to /fleet/vehicles/stats/feed:

curl -X GET \
  https://api.samsara.com/fleet/vehicles/stats/feed?types=engineStates \
  -H 'Authorization: Bearer <token>'

When a call to the feed endpoint is made without a cursor, the response will contain the most recent stats data for the requested vehicles:

{
    "data": [
        {
            "id": "123456789",
            "name": "Tommy the Tractor",
            "engineState": {
                "time": "2019-11-20T19:32:38Z",
                "value": "Off"
            }
        }
    ],
    "pagination": {
        "endCursor": "b864a4f6-0f90-4bbe-af48-171cacf62cca",
        "hasNextPage": false
    }
}

If hasNextPage is false, then new updates to the vehicles are not immediately available. We suggest waiting at least 5 seconds before requesting for updates:

Subsequent call to /fleet/vehicles/stats/feed with endCursor:

curl -X GET \
  'https://api.samsara.com/fleet/vehicles/stats/feed?types=engineState&after=b864a4f6-0f90-4bbe-af48-171cacf62cca' \
  -H 'Authorization: Bearer <token>'

The response contains two updates to the given vehicle that occurred after the provided endCursor.

{
    "data": [
        {
            "id": "123456789",
            "name": "Tommy the Tractor",
            "engineState": {
                "time": "2019-11-20T20:32:38Z",
                "value": "On"
            }
        },
        {
            "id": "123456789",
            "name": "Tommy the Tractor",
            "engineState": {
                "time": "2019-11-20T21:32:38Z",
                "value": "Off"
            }
        }
    ],
    "pagination": {
        "endCursor": "8e4fbc7b-24bf-4d23-9f3d-5d7826d34eaa",
        "hasNextPage": false
    }
}

Any subsequent calls with new endCursors will result in any updates that occurred after the given endCursor.

If hasNextPage is true, you can continue paginating through all the results. If hasNextPage is false, it is recommended that you wait 5 seconds before querying for new updates.

The following code demonstrates how to continuously poll for updates to stats data:

import requests
import json
import time

url = "https://api.samsara.com/fleet/vehicles/stats/feed"
headers = {"Authorization": "Bearer <token>"}
endCursor = ""
querystring = {"types": "engineStates"}

while True:
    if endCursor:
        querystring["after"] = endCursor
    response = requests.request("GET", url, headers=headers, params=querystring).json()
    vehicle_stats = response["data"]
    for vehicle in vehicle_stats:
        vehicle_id = vehicle["id"]
        name = vehicle["name"]
        for engineState in vehicle["engineStates"]
            # Do something with each state update
            # For example:
            database.write(vehicle_id, engineState)
    # do something with stats
    endCursor = response["pagination"]["endCursor"]
    if not response["pagination"]["hasNextPage"]:
        time.sleep(5)

Empty Pages or Short Pages

There is a chance you will see pages where hasNextPage == true, but the page has an empty data array or fewer than 512 vehicles in the array.

This is the result of vehicles whose stats are unknown. This is usually due to devices that have not been connected yet.

There may be more pages of vehicles with stats available. It is important that you always keep paginating while hasNextPage == true.

Get historical vehicle stats

The GET /fleet/vehicles/stats/history endpoint provides vehicle stat data between a given start time and end time, optionally filtered by tags or vehicles.

The startTime and endTime are required parameters, and accept RFC 3339 timestamps. Timezones are supported.

curl -X GET \
  'https://api.samsara.com/fleet/vehicles/stats/history?types=engineState&startTime=2019-10-20T09:00:00Z&endTime=2019-10-21T09:00:00Z' \
  -H 'Authorization: Bearer <token>'
{
    "data": [
        {
            "id": "123456789",
            "name": "Tommy the Tractor",
            "locations": [
                {
                    "time": "2019-10-20T09:02:30Z",
                    "engineState": "Off"
                },
                {
                    "time": "2019-10-21T06:00:00Z",
                    "engineState": "On"
                },
                {
                    "time": "2019-10-21T08:00:00",
                    "engineState": "Off"
                }
            ]
        }
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

The response will contain all of the stats updates for the requested vehicles between the given start time and end time.

The data array will contain an entry for each vehicle. The vehicle object will contain the vehicle's id, name, and an array of stats objects that contains the vehicle's stats updates between the given start time and end time. Each entry in the stats array will contain the time the stat update occurred.

The response will be paginated based on the number of vehicles and the length of the time range requested.

Empty Pages or Short Pages

There is a chance you will see pages where hasNextPage == true, but the page has an empty data array or fewer than 512 vehicles in the array.

This is the result of vehicles whose stats are unknown. This is usually due to devices that have not been connected yet.

There may be more pages of vehicles with stats available. It is important that you always keep paginating while hasNextPage == true.

Note that this endpoint is more susceptible to missed events due to connectivity issues than the feed endpoint is. If you request a very recent time range and the vehicle is experiencing connectivity issues, then there is a chance that events will not have been uploaded before you request them. If your use case dictates that you must continuously poll for very recent time ranges (an endTime less than 5 minutes ago), explore the feed endpoint as an alternative.

Updated 27 days ago



Vehicle Stats


Get real-time or historical vehicle stat data (odometers, engine state, fuel levels, engine hours)

Suggested Edits are limited on API Reference Pages

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