v5 API Overview

The ZENTRA Cloud v5 API is the latest-generation data interface from METER Group, designed to provide faster, more reliable, and more consistent access to environmental and device data.

This overview covers the concepts that apply across every v5 endpoint — the base URL, authentication, access control, rate limiting, pagination, and error handling. Read it once, then use the per-endpoint reference articles for parameters and response shapes.

Base URL

All v5 endpoints live under a single host:

Explore

Explore the v5 endpoint in the interactive reference.

Authentication

Every request is authenticated with your personal API key, passed in a request header:

The user is resolved from the key — you never pass a user ID. Each key only ever sees the devices and data it is authorized to access, so the same request made by two different users can return different results. A missing or invalid key returns 401 Unauthorized.

Your key is per-user and should be treated like a password. See API Token for where to find, copy, and regenerate it.

Data access control

Access to device data is controlled by the organization. You can discover a device if you are a member of its organization, either directly or through a workspace the device is shared into, at any role. Reading the device's data additionally requires an Administrator, Editor, or User role at that scope, so a Viewer can see a device in List Devices but cannot retrieve its measurements. List Devices reports the answer for each device in its can_read_data field.

Endpoints

The v5 surface is intentionally small. Each endpoint has its own reference article:

A typical integration uses both: call List Devices once to discover serial numbers and device metadata, then call Get Device Readings per device to pull measurements.

Pagination

Pagination differs by endpoint because the two endpoints return fundamentally different data, so check each endpoint's article for specifics:

• List Devices uses offset-style pagination with page_num and limit, ordered by device ID ascending. Iterate page_num=1, 2, 3, … up to total_pages.
• Get Device Readings uses calendar-month windows aligned to UTC. Each page holds a single calendar month of data, and a next_token is returned when more pages are available. In descending order (newest first), the first page contains only the portion of the current month up to your requested end, so it is often smaller than later pages. Each response also carries a next_url you can follow directly instead of assembling the next request yourself. It can also be paged by reading ID. Passing since_reading_id returns readings in ascending reading-ID order and overrides the time-range and direction parameters. This is the reliable way to take a complete copy of a device's history, or to poll for readings that arrived after the time they were measured. See the endpoint article.

Rate limiting

The v5 API rate limits each endpoint independently using the Generic Cell Rate Algorithm (GCRA), which allows short bursts and then a steady sustained rate. What a limit counts against differs by endpoint: List Devices is limited per user, Get Device Readings is limited per device. Requests beyond a limit return 429 Too Many Requests with a Retry-After header giving the number of whole seconds to wait before retrying. Standard HTTP retry libraries read Retry-After automatically.

For per-endpoint limits, reset behavior, and retry guidelines, see Rate Limiting.

Units

Endpoints accept a units parameter of metric or imperial. The default is metric. Measurements that use the same unit in both systems (kPa, mS/cm, W/m²) are returned unconverted, and each reading's unit field always reports the unit actually applied. Positions (cm or in) and elevations (m or ft) also follow units.

Data retention

Measurements are retained for 914 days (about 2.5 years). Data older than that cannot be retrieved through the API. The cutoff is rolling: it is recalculated on every request as the current time minus 914 days, and it applies to when a measurement was taken, not when it was uploaded. A Get Device Readings request that reaches back further than the cutoff is shortened to the cutoff rather than rejected. For any device that recorded before the cutoff, List Devices reports the cutoff as first_measurement, so both endpoints agree on what is retrievable. Because the cutoff moves forward every day, a stored first_measurement value goes out of date.

Status Codes

The API uses standard HTTP status codes. The ones you'll encounter across endpoints are 401 (authentication), 403 (not a member of the requested organization, or a role below User when reading data), 404 (unknown device, or a device outside the workspaces you can reach), 422 (invalid parameters), and 429 (rate limit).

See HTTP Status Codes for the full model and how to handle each. Endpoint articles note any endpoint-specific causes.

Device & sensor error codes

A non-zero error_code on a reading describes a problem with that measurement, not a failed request; the response itself is still 200 OK. Every Get Device Readings response includes a top-level error_codes object that maps each error_code appearing in values to its description, so you can display the reason without keeping your own lookup table. See Device & Sensor Error Codes for the full list.

Client libraries are available for R (zentraR) and Python (zentracloud) if you would rather not call the endpoints directly.