---
title: "v5 API Overview"
description: "The concepts shared across every ZENTRA Cloud v5 API endpoint — base URL, authentication, data access control, rate limiting, pagination, units, and errors. Start here."
url: "https://docs.zentracloud.io/l/en/article/zjky832943-api-v5"
category: "v5.0"
updated_at: "2026-11-05T19:39:03Z"
language: "en"
---

# 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.

[Tour the v5 API | ZENTRA Cloud](https://www.youtube.com/embed/iwjZ9t-72Rg?feature=oembed)

**New to the API?** Start with [Getting Started](/l/en/article/flaxog1o5b-getting-started-v5), which walks you from account creation to your first request.

#### Base URL

All v5 endpoints live under a single host:

https://api.zentracloud.io/v5

#### Explore

Explore the v5 endpoint in the interactive reference.

[OpenAPI/Swagger](https://api.zentracloud.io/)

#### Authentication

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

X-API-Key: YOUR\_API\_KEY

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](/l/en/article/xot1qptzgz-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:

| Endpoint                                                        | Method & path                     | What it does                                                                   |
|-----------------------------------------------------------------|-----------------------------------|--------------------------------------------------------------------------------|
| [List Devices](/l/en/article/7t31rdmwh4-list-devices)           | GET `/v5/devices`                 | Discover the devices your key can access and collect their `device_id` values. |
| [Get Device Data](/l/en/article/pep98lcz1h-get-device-readings) | GET`/v5/devices/{device_id}/data` | Pull time-series measurements for a single device.                             |

A typical integration uses both: call List Devices once to discover serial numbers and device metadata, then call Get Device Data 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 Data 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 Data 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](/l/en/article/f6wdg770d3-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 Data 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](/l/en/article/ajte070y7e-errors) 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 Data 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](/l/en/article/l1uopg3wo7-device-sensor-error-codes) for the full list.

Client libraries are available for R ([zentraR](/l/en/article/j1ejykpvpv-getting-started-with-zentra-r)) and Python ([zentracloud](/l/en/article/tlzgjas1wv-getting-started-with-the-zentra-cloud-python-sdk)) if you would rather not call the endpoints directly.
