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. To read a device's data, your user account must be a member of the organization that the device belongs to, and your role in that organization must be Administrator, Editor, or User. Workspace-level access counts as membership for device discovery.

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.

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.

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

Units

Accept a units parameter of metric or imperial. The default is metric.

Status Codes

The API uses standard HTTP status codes. The ones you'll encounter across endpoints are 401 (auth), 403 (not a member of the requested organization), 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.

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