Readings

Snapshot, historical, and feed access to time-series readings for assets and sensors via the Readings API.

Overview

Samsara allows you to retrieve and ingest time-series readings for assets and sensors in your organization using the Readings API. Readings provide a unified interface for accessing diagnostic data, environmental sensor data, trailer telemetry, tire conditions, and more.

Before you run the cURL examples on this page, store your API token in the SAMSARA_API_TOKEN environment variable and reference that variable in the Authorization header.

There are four endpoints that allow you to interact with readings data:

Endpoint	Description
/readings/definitions	Discover available readings, their data types, units, and metadata.
/readings/latest	Get a “snapshot” of the last known reading values.
/readings/history	Pull a historical report or feed of reading values over time.
/readings	Ingest new readings for API-created assets.

Entity Types

Readings are associated with an entity type. You must specify the entityType query parameter on every request (except /readings/definitions, where the optional entityTypes parameter filters the results). The following entity types are supported:

Entity Type	Description
asset	Vehicles, powered equipment, unpowered equipment, and other tracked assets.
sensor	Environmental monitors, cargo sensors, door monitors, and level monitors.

Definitions

The GET /readings/definitions endpoint is an introspection endpoint for discovering the set of readings including their name, description, data type, unit, and other metadata.

Use this endpoint to:

• Enumerate all available reading IDs before querying for data
• Discover the data type and enum values for a reading
• Check whether a reading supports ingestion via the API

curl --request GET 'https://api.samsara.com/readings/definitions' \
--header "Authorization: Bearer $SAMSARA_API_TOKEN" \
-G

Query Parameters

Parameter	Required	Description
ids	No	Comma-separated list of reading IDs. Up to 50. If not set, all readings returned.
entityTypes	No	Comma-separated list of entity types to filter by (e.g. asset, sensor).
after	No	Pagination cursor from a previous response.

Snapshot

The GET /readings/latest endpoint returns the last known reading values for a set of entities at the specified time.

This endpoint is suited for use cases where you need a point-in-time view of asset or sensor state rather than a continuous data stream. For example, you can use this endpoint to:

• Get the current engine speed, fuel level, and coolant temperature for all vehicles
• Get the last known reading values as of a specific point in time
• Periodically refresh known asset state at a frequency that matches your use case

curl --request GET 'https://api.samsara.com/readings/latest' \
-d readingIds='engineRpm,fuelLevelPerc,coolantTemp' \
-d entityType='asset' \
--header "Authorization: Bearer $SAMSARA_API_TOKEN" \
-G

Query Parameters

Parameter	Required	Description
readingIds	Yes	Comma-separated list of reading IDs. Up to 3 per request.
entityType	Yes	The entity type to fetch readings for (asset or sensor).
entityIds	No	Comma-separated list of entity IDs to filter by.
externalIds	No	Comma-separated list of external IDs to filter by (e.g. samsara.serial:ZPXKLMN7VJ).
asOfTime	No	Returns the last known values with timestamps less than or equal to this time. Defaults to now. RFC 3339 format.
includeExternalIds	No	Set to true to include external IDs in the response.
after	No	Pagination cursor from a previous response.

Historical Report

The GET /readings/history endpoint returns reading values within a specified time range.

This endpoint should not be used for continuous synchronization as it is more susceptible to “missing” data due to connectivity issues. For continuous synchronization, use the Feed mode instead.

This endpoint is best suited for cases such as:

• Back-filling historical reading data
• Ad-hoc querying of historical data between two timestamps
• Generating reports for a specific time window

curl --request GET 'https://api.samsara.com/readings/history' \
-d readingId='engineRpm' \
-d entityType='asset' \
-d startTime='2024-01-01T00:00:00Z' \
-d endTime='2024-01-02T00:00:00Z' \
--header "Authorization: Bearer $SAMSARA_API_TOKEN" \
-G

Query Parameters

Parameter	Required	Description
readingId	Yes	The reading ID to retrieve data for.
entityType	Yes	The entity type to fetch readings for (asset or sensor).
entityIds	No	Comma-separated list of entity IDs to filter by.
externalIds	No	Comma-separated list of external IDs to filter by.
startTime	No	Start of the time range (inclusive). RFC 3339 format.
endTime	No	End of the time range (exclusive). Defaults to now. RFC 3339 format.
feed	No	Set to true to enable feed mode for continuous synchronization.
includeExternalIds	No	Set to true to include external IDs in the response.
after	No	Pagination cursor from a previous response.

Data is returned where startTime <= happenedAtTime < endTime.

Feed

The GET /readings/history endpoint also supports a feed mode for continuously synchronizing reading data. Enable it by setting feed=true.

Feed mode should be used for synchronizing reading data over time. You repeatedly poll this endpoint, and each response provides a cursor for the next request so you receive only new data since the last call.

You can poll the endpoint every 5 seconds for near-real-time data, or every 24 hours for a daily sync. In either case, each poll returns all new reading updates since the last request.

Feed mode is better than historical report for synchronizing data because it is much less susceptible to “missing” data due to connectivity issues.

curl --request GET 'https://api.samsara.com/readings/history' \
-d readingId='engineRpm' \
-d entityType='asset' \
-d feed='true' \
--header "Authorization: Bearer $SAMSARA_API_TOKEN" \
-G

Feed Polling Workflow

1. Initial request

   Make an initial request with feed=true (and optionally startTime).

2. Process data

   Process all data items in the response.

3. Capture cursor

   Use the endCursor from pagination as the after parameter in your next request.

4. Continue or wait

   If hasNextPage is true, immediately make the next request. If hasNextPage is false, wait at least 5 seconds before polling again.

5. Repeat

   Repeat from the data-processing step.

Important: In feed mode, the response always includes an endCursor, even when hasNextPage is false. Always use this cursor for the next request to avoid re-fetching data you’ve already received.

Ingesting Readings

The POST /readings endpoint allows you to ingest batches of reading data points for API-created assets.

Ingesting readings is only supported for assets created using the POST /assets endpoint with readingsIngestionEnabled set to true. Not all readings support ingestion — use the GET /readings/definitions endpoint and check the ingestionEnabled field to see which readings accept ingested data.

When ingesting location data, the reading ID location must be used and the value object must contain at least the following fields: speed, latitude, longitude.

curl --request POST 'https://api.samsara.com/readings' \
--header "Authorization: Bearer $SAMSARA_API_TOKEN" \
--header 'Content-Type: application/json' \
-d '{
    "data": [
        {
            "readingId": "airInletPressure",
            "entityId": "123451234512345",
            "entityType": "asset",
            "happenedAtTime": "2024-10-27T10:00:00Z",
            "value": 101.3
        },
        {
            "readingId": "location",
            "entityId": "123451234512345",
            "entityType": "asset",
            "happenedAtTime": "2024-10-27T10:00:00Z",
            "value": {
                "latitude": 37.7749,
                "longitude": -122.4194,
                "speed": 45.0
            }
        }
    ]
}'

Constraints

• Up to 1000 data points per request.
• happenedAtTime must not be older than the last known reading for the same series.
• Only asset entity type is currently supported for ingestion.

Reading Categories

All readings are organized by category. Use the GET /readings/definitions endpoint to retrieve the authoritative, up-to-date list with full metadata.

This is not an exhaustive list. Your organization may have access to additional readings based on enabled features or custom configurations. Use the /readings/definitions endpoint to retrieve all available reading IDs for your organization.

Category	Entity Type	Description
diagnostic	asset	Core asset diagnostics: engine, fuel, GPS, temperatures, pressures, EV, electrical, and more.
obd	asset	Advanced OBD data: ADAS/AEBS, cruise control, stability control.
smartTrailer	asset, sensor	Smart trailer telemetry, door monitors, environment sensors, and brake monitoring.
reefer	asset	Refrigerated trailer: zone temperatures, set points, state, fuel, alarms.
tireCondition	asset	Per-tire pressure and temperature across up to 3 axles.
levelMonitoring	asset, sensor	Tank fill levels, volumes, masses, and fluid status.
pressureVesselHealth	asset	Pressure vessel temperature, pressure, and battery level.

For a complete enumeration of reading IDs, labels, descriptions, data types, and units within each category, query the /readings/definitions endpoint. Your organization’s available readings depend on enabled features and asset configurations.

Pagination

All Readings API endpoints use cursor-based pagination. Each paginated response includes a pagination object:

{
    "pagination": {
        "endCursor": "dXNlcjpVMEc5V0ZYMnEw",
        "hasNextPage": true
    }
}

• endCursor: Pass this value as the after query parameter in your next request to get the next page.
• hasNextPage: If true, more data is available. Continue paginating until hasNextPage is false.