Table of Contents
API Documentation
The API provides a flexible, and developer‑friendly interface for programmatically accessing environmental measurement and device data stored in ZENTRA Cloud 2.0
API Overview
The ZENTRA Cloud v5 API is the latest-generation data interface from METER Group, designed to provide faster, more consistent access to environmental data.
Rate Limiting
The Generic Cell Rate Algorithm (GCRA) is precise, burstable rate limiting algorithm. It tracks a "Theoretical Arrival Time" (TAT) for each client and allows requests as long as they do not arrive "too early" according to the configured rate. GCRA is widely used in telecommunications, API gateways, and distributed systems where fairness and precise burst control are required.
v5 has a burst limit of 5, and a steady state rate of 1 call per minute.
How GCRA Works in v5
- Initial Burst Allowance: Clients can make up to 5 immediate requests without delay if they have been idle. This is the allowed burst capacity.
- Steady‑State Rate: After the burst capacity is consumed, additional requests are limited to the steady rate of 1 request per minute.
- Burst Reset Behavior: The burst allowance fully resets if no requests are made for a period equal to burst_limit × 60 seconds (for 5 bursts, this is 300 seconds).
- After this idle period, clients regain the ability to make all 5 burst requests immediately.
- Handling Early Requests: If a request arrives sooner than allowed by the GCRA schedule, the algorithm calculates a next time to call timestamp. The client must wait this long before the next request will be accepted.
Pagination
Data responses are paginated using calendar‑month windows aligned to UTC. Each page contains the data for a single calendar month, and a next_token is returned when additional pages are available.
When requesting data in descending order (newest first), the first page contains only the portion of the current month up to the requested end_datetime orend_timestamp. As a result, this initial page is often smaller than the subsequent pages, which each contain a full month of data.
How to get started
Data Access Control
Access to device data is controlled by the organization. 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.
Create Account
Follow our Getting Started guide:
Where to Find Your API Key
API Token Keys are provided per user. Your API Key can be found under your ZENTRA Cloud user account, under Integrations. You can copy the token ID or regenerate the token ID.
Try it Out
Parameters
string (path) | The unique identifier of the device. Example : |
string (query) | Order by which data is retrieved and displayed by date. Available values: Default value: |
(query) | An ISO datetime string. A start datetime without a timezone will be considered as having a UTC timezone. Users should not input both datetimes and timestamps, only one or the other. Example: or Example: |
(query) | An ISO datetime string. An end datetime without a timezone will be considered as having a UTC timezone. Users should not input both datetimes and timestamps, only one or the other. Example: or Example: |
(query) | Unix timestamp representing seconds since Jan. 1, 1970 00:00 UTC. Users should not input both datetimes and timestamps, just one or the other. Example: |
(query) | Unix timestamp representing seconds since Jan. 1, 1970 00:00 UTC. Users should not input both datetimes and timestamps, just one or the other. Example: |
(query) | The string needed to get the next pagination set. |
boolean (query) | Coming Soon! Returns the latest datapoint, supersedes datetime and timestamp parameters. Default value: Example: |
(query) | Coming Soon! Gives more information on the field passed. Example: |
string (query) | The units that the data will return in. Available values: Default value: Example: |
Example Queries by Language
Curl
curl --request GET \
--url 'https://api.zentracloud.io/v5/devices/z6-00930/data?start_datetime=2026-05-29T00%3A00%3A00-00%3A00&end_datetime=2026-05-30T23%3A59%3A00-00%3A00&direction=descending&units=metric' \
--header 'Accept: */*' \
--header 'Host: <calculated at runtime>' \
--header 'X-API-Key: <<token>>'
JavaScript - Fetch
const url = 'https://api.zentracloud.io/v5/devices/z6-00930/data?start_datetime=2026-05-29T00%3A00%3A00-00%3A00&end_datetime=2026-05-30T23%3A59%3A00-00%3A00&direction=descending&units=metric';
const options = {
method: 'GET',
headers: {'X-API-Key': '<<token>>', Accept: '*/*', Host: '<calculated at runtime>'}
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
Python - Requests
import requests
url = "https://api.zentracloud.io/v5/devices/z6-00930/data"
querystring = {"start_datetime":"2026-05-29T00:00:00-00:00","end_datetime":"2026-05-30T23:59:00-00:00","direction":"descending","units":"metric"}
headers = {
"X-API-Key": "<<token>>",
"Accept": "*/*",
"Host": "<calculated at runtime>"
}
response = requests.get(url, headers=headers, params=querystring)
print(response.json())
PHP - cURL
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.zentracloud.io/v5/devices/z6-00930/data?start_datetime=2026-05-29T00%3A00%3A00-00%3A00&end_datetime=2026-05-30T23%3A59%3A00-00%3A00&direction=descending&units=metric",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Accept: */*",
"Host: <calculated at runtime>",
"X-API-Key: <<token>>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
R - httr
library(httr)
url <- "https://api.zentracloud.io/v5/devices/z6-00930/data"
queryString <- list(
start_datetime = "2026-05-29T00:00:00-00:00",
end_datetime = "2026-05-30T23:59:00-00:00",
direction = "descending",
units = "metric"
)
encode <- "raw"
response <- VERB("GET", url, query = queryString, add_headers('X-API-Key' = '<<token>>', 'Host' = '<calculated at runtime>'), content_type("x-unknown"), accept("*/*"), encode = encode)
content(response, "text")
How did we do?
API Token
