Historical Report

Pull a historical report of GPS and onboard diagnostic data between a given start time and end time.

Introduction

The /fleet/vehicles/stats/history endpoint allows you to pull a historical report of GPS and onboard diagnostic data. See the query parameters section for details on which types of data are available.

If you’re looking for a way to sync telematics data (either continuously or on a periodic basis), see the Telematics Feed guide instead. The /feed endpoint is designed for synchronization use cases and less susceptible to “missing” data due to connectivity issues.

This endpoint is most suited for the use cases such as:

• Back-filling historical vehicle stat data
• Ad-hoc querying of a historical time period of data

Start and End Time

The main features of this endpoint are the startTime and endTime parameters, which are required.

The following request retrieves engine state data for the 24 hours between June 23, 2020 and June 24, 2020 in UTC time. The types parameter indicates which vehicle stats to query. See the Timestamps guide for details on timestamp formatting.

curl --request GET 'https://api.samsara.com/fleet/vehicles/stats/history' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
-d types='engineStates' \
-d startTime='2020-07-23T00:00:00Z' \
-d endTime='2020-07-24T00:00:00Z' \
-G

The response contains a data array, which contains an entry for each vehicle in the fleet. In this example, there are two vehicles: "Little Red", and "Big Red". The engineStates array for each vehicle lists all the engine states changes during the requested time range for that vehicle.

{
    "data": [
        {
            "engineStates": [
                {
                    "time": "2020-07-23T22:36:43Z",
                    "value": "On"
                },
                {
                    "time": "2020-07-23T23:36:52Z",
                    "value": "Off"
                }
            ],
            "id": "281474977075805",
            "name": "Little Red"
        },
        {
            "engineStates": [
                {
                    "time": "2020-07-22T10:53:05Z",
                    "value": "On"
                },
                {
                    "time": "2020-07-22T15:31:20Z",
                    "value": "Off"
                }
            ],
            "id": "212014918732717",
            "name": "Big Red"
        }
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

Notice that the time-series data is grouped by vehicle. This is important to take into account when processing or storing the data.

Pagination

The data returned by this endpoint may be paginated to improve performance. This means that if there are a large number of vehicles in the fleet and/or you query for a long time period, then the results will be returned across multiple pages.

The hasNextPage field indicates whether there are more pages in your query. If so, you can use the endCursor to request the subsequent page.

The following sample code demonstrates how to paginate through all pages in the query to make sure that you receive all the data you requested:

import requests

url = "https://api.samsara.com/fleet/vehicles/stats/history"
params = {
    "types": "engineStates",
    "startTime": "2020-07-23T00:00:00Z",
    "endTime": "2020-07-24T00:00:00Z"
}
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN"
}

hasNextPage = True
while hasNextPage:
    response = requests.request("GET", url, headers=headers, params=params).json()

    # Process this page of data
    for vehicle in response["data"]:
        # Extract the vehicle ID and name
        vehicle_id = vehicle["id"]
        vehicle_name = vehicle["name"]

        # Process all the engine state events for this vehicle
        for event in vehicle["engineStates"]:
            value = event["value"]
            timestamp = event["time"]
            # do something with the data

    # Update `hasNextPage` and collect the `endCursor` for the next call
    hasNextPage = response["pagination"]["hasNextPage"]
    params["after"] = response["pagination"]["endCursor"]