Readings

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. See Reading Categories for a full catalog of available readings.

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:

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:

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 (look at the ingestionEnabled field on each definition)

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

{
    "data": [
        {
            "readingId": "engineRpm",
            "entityType": "asset",
            "label": "Engine Speed",
            "description": "Represents the engine speed in revolutions per minute (RPM).",
            "category": "diagnostic",
            "type": {
                "dataType": "integer",
                "unit": {
                    "measurementType": "rotationalSpeed",
                    "baseUnit": "rpm"
                }
            },
            "enumValues": null,
            "ingestionEnabled": true
        },
        {
            "readingId": "engineState",
            "entityType": "asset",
            "label": "Engine State",
            "description": "Indicates the current state of the engine, such as running, stopped.",
            "category": "diagnostic",
            "type": {
                "dataType": "integer"
            },
            "enumValues": [
                { "symbol": "off", "label": "Off" },
                { "symbol": "running", "label": "Running" },
                { "symbol": "idling", "label": "Idling" }
            ],
            "ingestionEnabled": true
        }
    ],
    "pagination": {
        "endCursor": "...",
        "hasNextPage": false
    }
}

Query Parameters

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

{
    "data": [
        {
            "readingId": "engineRpm",
            "entityId": "123456",
            "value": 3000,
            "happenedAtTime": "2024-01-27T07:06:25Z"
        },
        {
            "readingId": "fuelLevelPerc",
            "entityId": "123456",
            "value": 72.5,
            "happenedAtTime": "2024-01-27T07:05:10Z"
        }
    ],
    "pagination": {
        "endCursor": "...",
        "hasNextPage": false
    }
}

Query Parameters

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

{
    "data": [
        {
            "entityId": "123456",
            "value": 3000,
            "happenedAtTime": "2024-01-01T08:15:30Z"
        },
        {
            "entityId": "123456",
            "value": 2800,
            "happenedAtTime": "2024-01-01T08:17:45Z"
        }
    ],
    "pagination": {
        "endCursor": "...",
        "hasNextPage": true
    }
}

Query Parameters

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

{
    "data": [
        {
            "entityId": "123456",
            "value": 3100,
            "happenedAtTime": "2024-01-27T08:00:05Z"
        }
    ],
    "pagination": {
        "endCursor": "dXNlcjpVMEc5V0ZYMnEw",
        "hasNextPage": false
    }
}

Feed Polling Workflow

1. Make an initial request with feed=true (and optionally startTime).
2. Process all data items in the response.
3. Use the endCursor from pagination as the after parameter in your next request.
4. If hasNextPage is true, immediately make the next request.
5. If hasNextPage is false, wait at least 5 seconds before polling again to avoid unnecessary requests.
6. Repeat from step 2.

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.

Note: Ingesting readings is only supported for assets created using the POST /assets endpoint with readingsIngestionEnabled set to true. Not all readings support ingestion — see the Ingestion Enabled column in each Reading Categories table below, or check the ingestionEnabled field returned by GET /readings/definitions.

Note on location: The location reading ID is overloaded — the read-path reading (returned by GET /readings/latest and GET /readings/history) is a String describing the asset's current address, while the ingest-path reading is a separate Object value that must contain latitude, longitude, and speed. When ingesting location data, always send the Object form shown in the example below.

curl --request POST 'https://api.samsara.com/readings' \
--header "Authorization: Bearer $SAMSARA_API_TOKEN" \
--header 'Content-Type: application/json' \
-d '{
    "data": [
        {
            "readingId": "engineRpm",
            "entityId": "123451234512345",
            "entityType": "asset",
            "happenedAtTime": "2024-10-27T10:00:00Z",
            "value": 2400
        },
        {
            "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. The sections below document every available reading grouped by category. The Ingestion Enabled column indicates whether a reading can be sent to the POST /readings endpoint.

Note: 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, and rely on its ingestionEnabled field as the source of truth for ingestion support.

Diagnostic

Entity type: asset

Core asset diagnostics including engine metrics, fuel, GPS location, temperatures, pressures, electrical, EV data, and more.

OBD

Entity type: asset

Advanced OBD data including ADAS/AEBS state, cruise control, and stability control readings.

Smart Trailer

Entity type: asset, sensor

Smart trailer telemetry, door monitors, environment sensors, and brake monitoring.

Reefer

Entity type: asset

Refrigerated trailer data including zone temperatures, set points, reefer state, fuel, and alarms.

Tire Condition

Entity type: asset

Per-tire pressure and temperature readings across up to 3 axles with 4 tire positions each (left outer, left inner, right inner, right outer).

Level Monitoring

Entity type: asset, sensor

Tank fill levels, volumes, masses, and fluid status for level monitors.

Pressure Vessel Health

Entity type: asset

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.