Guides
SUPPORTFEEDBACK

Tell Tale Statuses Monitoring

Suggest Edits

Tell tales are vehicle dashboard indicators that provide real-time status information about various vehicle systems and conditions. Samsara specifically reports tell tales that indicate warnings or error conditions requiring attention, such as engine failures, transmission issues, or oil level warnings. Unlike fault codes which provide specific diagnostic trouble codes from the ECU, tell tales reflect the current state of vehicle warning lights and error indicators on the dashboard.

There are two ways for your application to integrate with Samsara's tell tales monitoring:

  • Polling the REST API for tell tales - In this strategy, you make HTTP requests to Samsara's REST API, retrieving any tell tales that may have occurred over a desired time range. You determine how frequently to make requests and poll for data.
  • Configuring a fault code webhook alert - Tell tales data included alongside fault codes in webhook payloads. See the Fault Monitoring for a full overview.
    Note: There are no standalone webhook alerts for tell tales. Tell tales webhook data is only available as part of fault code alerts. For comprehensive tell tales monitoring, use the direct API endpoints described below.

Polling the REST API

There are three options for pulling tell tales data from the REST API:

  • Get currently active tell tales
  • Generate a tell tales history report for a given time period
  • Follow a feed of tell tales events

Each of these use cases utilizes the Vehicle Stats APIs. See the Telematics for a full overview.

Currently Active Tell Tales

The following API call will return the most recent tell tales reading for each vehicle in the fleet:

curl --request GET 'https://api.samsara.com/fleet/vehicles/stats?types=tellTales' \
--header 'Authorization: Bearer <<token>>'

The JSON response will contain a data array with an entry for each vehicle in the fleet:

{
    "data": [
        {
            "id": "281474977075805",
            "name": "Vehicle A",
            "tellTales": {...}
        },
        ...more vehicles
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

The tellTales field will contain details on the last tell tales reading for that vehicle.

The response may contain multiple pages of data. See the Pagination guide for details on how to use the pagination field to retrieve all the pages of data.

Tell Tales History Report

The following API call will return all tell tales readings over a desired time range.

The startTime and endTime query parameters accept RFC 3339 format (e.g. 2020-09-01T00:00:00Z for UTC time or 2020-09-01T00:00:00-07:00 to use a timezone offset).

curl --request GET 'https://api.samsara.com/fleet/vehicles/stats/history?types=tellTales&startTime=2020-09-01T00:00:00Z&endTime=2020-10-01T00:00:00Z' \
--header 'Authorization: Bearer <<token>>'

The JSON response will contain a data array with an entry for each vehicle in the fleet:

{
    "data": [
        {
            "id": "281474977075805",
            "name": "Vehicle A",
            "tellTales": [
                {...},
                {...},
                ...more tell tales
            ]
        },
        ...more vehicles
    ],
    "pagination": {
        "endCursor": "",
        "hasNextPage": false
    }
}

The tellTales field will contain an array of tell tales readings that occurred during the requested time range.

The response may contain multiple pages of data. See the Pagination section of the Telematics History guide for details on how to use the pagination field.

Tell Tales Feed

The following API call will initiate a feed of tell tales readings.

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

The JSON response will contain a data array with an entry for each vehicle in the fleet. The tellTales field of each vehicle will contain the most recent tell tales reading. The pagination object will contain an endCursor for the next poll to the feed:

{
    "data": [
        {
            "id": "281474977075805",
            "name": "Vehicle A",
            "tellTales": [
              {...}
            ]
        }, 
	...more vehicles
    ],
    "pagination": {
        "endCursor": "19dae03e-6d49-4bf8-8303-435b46587257",
        "hasNextPage": false
    }
}

You can poll for updates to the feed by submitting the cursor value to the after query parameter:

curl --request GET 'https://api.samsara.com/fleet/vehicles/stats/feed?types=tellTales&after=19dae03e-6d49-4bf8-8303-435b46587257' \
--header 'Authorization: Bearer <<token>>'

The response will list any new tell tales readings in the tellTales array, and the pagination object will provide you with a new cursor to use for the next poll to the endpoint

{
    "data": [
        {
            "id": "281474977075805",
            "name": "Vehicle A",
            "tellTales": [
                {...},
                ...new readings since last poll
            ]
        },
        ...more vehicles
    ],
    "pagination": {
        "endCursor": "37976de4-4280-401d-9951-ecf78124eef8",
        "hasNextPage": false
    }
}

See the Telematics Sync guide for details on how to work with the /feed endpoint.

tellTales

Depending on the endpoint you choose, the tellTales field will either be an array of tell tales readings, or it will be a single tell tale reading.

{
   "time": "2024-10-27T14:11:00Z",
   "value": [
     {
       "name": "Engine Failure",
       "condition": "Yellow"
     }
   ]
}

The tellTales field contains the following structure:

  • time - RFC 3339 timestamp when the tell tales status was recorded
  • value - Array of active tell tales indicators, each containing:
    • name - Description of the tell tale indicator (e.g., "Engine Oil Level", "Transmission Failure", "Battery Warning")
    • condition - Severity level of the tell tale indicator (e.g., "Yellow", "Red")

Updated 3 days ago