List sensor readings
The workspace's environmental readings, newest first, a page at a time. Narrow them to one device, one growing room or one kind of measurement, and use since and until to fetch only the readings taken within a window.
https://app.xplantpro.com/read:sensor_readingsPages are larger here than on other lists: 100 readings by default and up to 1,000. To read further back than one page reaches, follow meta.next_cursor with the same filters until it comes back null. Readings taken at the same moment keep a fixed order, so none is skipped or repeated.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
device_id | string (uuid) | No | Only readings from this device. |
room_id | string (uuid) | No | Only readings for this growing room. |
type | "temperature" | "humidity" | "ph" | "co2" | "light" | "other" | No | Only this kind of reading. |
since | string (date-time) | No | Only readings taken at or after this time, as an ISO 8601 timestamp. |
until | string (date-time) | No | Only readings taken at or before this time, as an ISO 8601 timestamp. Must not be earlier than since. |
limit | integer | No | Page size. Values above 1,000 are capped at 1,000. Default 100. From 1 to 1000. |
offset | integer | No | Number of records to skip. Prefer cursor where a list offers it: an offset shifts when records are added ahead of it. Default 0. At least 0. |
cursor | string | No | Continue from the previous page: pass its meta.next_cursor unchanged, with the same filters. Treat it as opaque. Not combinable with offset. Up to 2048 characters. |
Example
curl "https://app.xplantpro.com/api/v1/sensor-readings?device_id=5f7a9c1e-3b5d-4f7a-9c1e-3b5d7f9a1c3e&type=temperature&since=2026-09-24T00%3A00%3A00Z&until=2026-09-25T00%3A00%3A00Z&limit=1000" \
-H "Authorization: Bearer $XPLANT_API_KEY"Response
200 with { "ok": true, "data": … }. data is an array. To get the next page, pass meta.next_cursor back as cursor; it is null on the last page. See Pagination.
| Field | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | Yes | — |
device_id | string (uuid) | Yes | — |
team_id | string (uuid) | Yes | The id of the workspace the reading belongs to. |
room_id | string | null (uuid) | Yes | — |
type | string | Yes | What was measured: temperature, humidity, ph, co2, light, other. |
value | number | Yes | — |
unit | string | Yes | — |
recorded_at | string | Yes | When the reading was taken, as an ISO 8601 timestamp. |
notes | string | null | Yes | — |
created_at | string | Yes | — |
{
"ok": true,
"data": [
{
"id": "f1a7c3e9-2b4d-4f6a-8c0e-3d5b7a9c1e24",
"device_id": "8e3b1f52-6c0d-4a7e-9b21-5f4d8c2a7e13",
"team_id": "5d2e8b17-9c4a-4e3f-b6d0-1a7c9e2f4b83",
"room_id": "2c6f9a41-7d3e-4b8a-a1c5-9e0d4f7b3a26",
"type": "temperature",
"value": 24.1,
"unit": "°C",
"recorded_at": "2026-09-25T14:00:00.000Z",
"notes": null,
"created_at": "2026-09-25T14:00:31.000Z"
}
]
}The envelope can also carry meta:
| Field | Type | Required | Description |
|---|---|---|---|
next_cursor | string | null | Yes | Pass as cursor to fetch the next page. null means this is the last page. |
| Response header | Meaning |
|---|---|
X-Request-Id | Identifies this request. Include it when you contact support. |
Errors
| Status | Code | When |
|---|---|---|
401 | UNAUTHORIZED | The key is missing, malformed or revoked, or its owner is no longer a member of the workspace. |
402 | PAID_PLAN_REQUIRED | The workspace's plan does not include the API. The full API is included with xPlant+ Teams and Enterprise; on Hobby and Pro Lab, keys can connect devices only. |
403 | FORBIDDEN | The key lacks a scope this operation requires, or its owner's current role in the workspace cannot use it — a key never does more than its owner can in xPlant. error names the scope, and for a role, the role it needs. |
403 | DEVICE_TOKEN_NOT_ACCEPTED | A device token was sent; this operation needs a workspace API key. |
422 | VALIDATION_ERROR | Both cursor and offset were sent; use one. |
422 | INVALID_CURSOR | The cursor is malformed, or came from a different list or different filters. Start again without it. |
422 | VALIDATION_ERROR | A query parameter is malformed: device_id or room_id is not a UUID, since or until is not a timestamp, since is later than until, or limit is not a whole number. error names the parameter, for example device_id: must be a UUID. |
429 | RATE_LIMIT_EXCEEDED | Too many requests for this key, device token or workspace. Wait Retry-After seconds. |
500 | READINGS_QUERY_FAILED | The readings could not be read. Retry later. |
Branch on code, never on the error text. See Errors.
Revoke a device token
Stops one device token working: the next request made with it is refused as unauthorized. The token stays in the device's token list, marked revoked with the time it was revoked, so the list remains a complete history of the device's credentials.
Submit sensor readings
Stores readings from a device. Send one reading, or up to 500 at once as { "readings": [...] }. Batch them: a gateway that buffers readings and posts every 30 to 60 seconds uses a small fraction of the requests of one that posts each reading as it is taken.