---
title: "[beta] Ingest Readings"
method: POST
path: "/readings"
tags: ["Beta APIs"]
---

# \[beta\] Ingest Readings

`POST /readings`

## Request

- Base URL: `https://api.samsara.com`
- URL: `https://api.samsara.com/readings`
- Auth: HTTP bearer

Ingest new readings. This endpoint allows the ingestion of batches of readings.

Ingesting readings is only supported for assets created using the POST /assets API endpoint with readingsIngestionEnabled set to true. To see a full list of readings available for ingestion use the GET readings definitions API.


Readings that currently support ingestion (by category):


<details>
<summary><strong>ingestible</strong></summary>

* `batteryVoltage`
* `coolantTemp`
* `ecuFuelLevelMillipercent`
* `engineHours`
* `engineRpm`
* `engineState` (values: off | running | idling)
* `faultCodes`
* `fuelLevelPerc`
* `gps`
* `odometerEcu`
* `oilPressure`

</details>

When ingesting GPS location data, use the readingID 'gps'. The value object must contain the following fields: 'latitude' (decimal degrees), 'longitude' (decimal degrees), and 'speed' (meters per second).

Related guide: [Readings](https://developers.samsara.com/docs/readings).

 <b>Rate limit:</b> 10 requests/sec (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).

To use this endpoint, select **Write Readings** under the Readings category when creating or editing an API token. <a href="https://developers.samsara.com/docs/authentication#scopes-for-api-tokens" target="_blank">Learn More.</a>
 

 **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href="https://forms.gle/zkD4NCH7HjKb7mm69" target="_blank">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href="https://www.samsara.com/help" target="_blank">submit a case</a> to our support team.

## Request body

- ReadingsPostReadingsRequestBody
  - `data` ReadingDatapointRequestBody[], required: An array of readings data points to create.
    - `entityId` string: Samsara entity ID. Required if externalId is not provided. In case of an asset, it’s the assetId. If the asset is not yet present in the system, it is required to create a new one via the /assets endpoint.
    - `entityType` 'asset', required: The type of the entity (e.g., asset). Valid values: `asset`
    - `externalId` string: An external ID in key:value format. Required if entityId is not provided. Use this to reference an asset by its external ID instead of the Samsara entity ID.
    - `happenedAtTime` string, required: The timestamp of when the reading happened in RFC 3339 format. happenedAtTime must not be older than the last known reading for the same series.
    - `readingId` string, required: The ID of the reading, you can get it from the /readings/definitions endpoint.
    - `value` string, required: The value of the reading. Can be any object. See the /readings/definitions endpoint for the value type for each reading.

## Response `201`

Created response.

## Other responses

- `401`: Unauthorized response.
- `404`: Not Found response.
- `405`: Method Not Allowed response.
- `413`: Content Too Large response.
- `429`: Too Many Requests response.
- `500`: Internal Server Error response.
- `501`: Not Implemented response.
- `502`: Bad Gateway response.
- `503`: Service Unavailable response.
- `504`: Gateway Timeout response.
- `default`: Bad Request response.

---

[API](https://skmtc.dev/samsara/apis/samsara-api.md) - [All operations](https://skmtc.dev/samsara/apis/samsara-api/llms.txt) - [OpenAPI document](https://skmtc.dev/samsara/apis/samsara-api/revisions/a9e35d4999be?raw)