---
title: "US Server API"
description: "Documentation for the ZENTRA Cloud API."
url: "https://docs.zentracloud.io/l/en/article/gbv2iyxhar-api-v-3-0-us"
category: "v3.0/4.0"
updated_at: "2026-05-12T22:37:04Z"
language: "en"
---

# US Server API

This article details where and how to use the documentation for the US server API.

* * *

#### US Server

Swagger [https://zentracloud.com/api/v4/documentation/](https://zentracloud.com/api/v4/documentation/)

**Latest Version:**  
v4 of the ZENTRA Cloud API is now available for production. METER recommends new clients start with v4. Existing clients can switch to using v4 if they encounter issues with pagination in v3. Both v3 and v4 support queries for ATMOS 41W, ZL6, EM60G and EM50G devices. The documentation for v3 and v4 is the same, users can simply change the version number in the endpoint URL from "v3" to "v4".

**Call Limits:**  
Users are limited to a total of 60 calls per minute(60sec), and each device is limited to 1 call per minute(60sec). One user can make 60 calls to 60 different devices in a 60 second period.

**Units:**  
To set the units, log in to your account at zentracloud.com and click the wrench icon from the main menu, and select **Measurement Units**. Edit your preferred units and click **Accept**. See the [Setting your preferred measurement units article here](https://docs.zentracloud.com/l/en/article/tqj9dl8cym-measurement-units).

* * *

#### How to start

- Sign up at [www.zentracloud.com](https://zentracloud.com/accounts/login/) if you haven't got your ZENTRA API key yet.
- Select **API** from the main menu.
- On the **Keys** tab click **Copy token**.

![](https://files.helpdocs.io/la7ra8dc1e/articles/gbv2iyxhar/1636742395759/ezgif-com-gif-maker-2.gif)

* * *

#### Run a test

- Navigate to the [API v4](https://zentracloud.com/api/v4/documentation/) Swagger documentation
- Select **Authorize**.
- Paste your token ID.
- Click **Authorize**.

![](https://files.helpdocs.io/la7ra8dc1e/articles/gbv2iyxhar/1636742704798/ezgif-com-gif-maker.gif)

* * *

#### GET

- To view an example, press the **GET** readings button.

* * *

#### Parameters

Experiment with different *start\_date*, *end\_date*, or *start\_mrid* and *end\_mrid* query parameters. Only start\_date and end\_date or start\_mrid and end\_mrid parameters need to be defined in the request, not both. MRID stands for "Measurement Record ID" and increases as the number of records on the device increases.

**device\_sn**

string

*(query)*

The serial number of the device having data requested. `z6-12345`

**start\_date**

string ($date)

(query)

Start date of time range. Defaults to date of first reading of device. Overrides start\_mrid. `2025-07-01 00:00`

**end\_date**

string ($date)

(query)

End date of time range. Defaults to date of last reading of device. Overrides end\_mrid. `2025-07-31 23:59`

**start\_mrid**

integer

(query)

Start mrid of mrid range. Defaults to mrid of first reading from Device. `3500`

**end\_mrid**

integer

(query)

End mrid of mrid range. Defaults to mrid of last reading from Device. `3800`

**output\_format**

string

(query)

The data structure of the response content. Defaults to json. Other options include pandas dataframe and csv. `json`, `df`, `csv`

**page\_num**

integer

(query)

Page number. Defaults to 1. `2`

**per\_page**

integer

(query)

Number of readings per page. Defaults to 500. Max is 2000. `1000`

**device\_depth**

boolean

(query)

When set to true, the API will return the sensor depth as part of the device metadata payload. `true`

**location**

boolean

(query)

When set to true, the API will return the logger location history(lat/lon) `true`

**sort\_by**

string

(query)

Sort the readings in ascending or descending order. Defaults to descending. `ascending`, `descending`

* * *

#### Examples

View examples in *json*, *csv* or *pandas Dataframe*.

![](https://files.helpdocs.io/la7ra8dc1e/articles/gbv2iyxhar/1636741262498/ezgif-com-gif-maker.gif)

* * *

#### Example Code Snippet

Copy the code snippet below, then edit the token, device serial number, and start and end dates.

```python
import requests # pip install requestsimport pandas # pip install pandasdef get_with_credentials(tok, uri, **kwargs):    # just in case we forget to put "Token MyToken"    token = tok if tok.lower().startswith("token") else f"Token {tok}"    headers = {"Authorization": token}    return requests.get(uri, headers=headers, **kwargs)def get_readings_response(sn, start_date, end_date, **extra_kwargs_for_endpoint):    server = extra_kwargs_for_endpoint.get("server", "https://zentracloud.com")    url = f"{server}/api/v4/get_readings/"    default_args = {        'output_format': "df",        'per_page': 1,        'page_num': 1,        'sort_by': 'desc',        'start_date': start_date,        'end_date': end_date    }    data = {**default_args, **extra_kwargs_for_endpoint, "device_sn": sn}    tok = extra_kwargs_for_endpoint.pop("token", "")    return get_with_credentials(tok, url, params=data)def get_readings_dataframe(sn,start_date,end_date,**extra_kwargs_for_endpoint):    res = get_readings_response(sn,start_date,end_date,**extra_kwargs_for_endpoint)    if(res.ok):        data = res.json()        return pandas.DataFrame(**json.loads(data["data"]))    return res#fill in your token, device serial number and start and end dates here.tok = "Token <Your Token>"sn="z6-#####"start_date="2024-04-01 00:00:00"end_date="2024-04-02 00:00:00"#specify the server here.server="https://zentracloud.com"df = get_readings_dataframe(sn, start_date, end_date, token=tok, server=server)print(df)
```

* * *

#### Error Flags

Each measurement reading includes an `error_flag` field that indicates whether the value is suspect or invalid due to sensor or data issues.

- `error_flag: true` - The measurement is suspect or bad. Users should treat the value as unreliable or ignore it.
- `error_flag: false` - The measurement is considered valid.

If the error\_flag is true, additional context may be provided in the error\_description field, and detailed error types can be found in the `metadata.errors` array.

##### Example

```json
"Wind Speed": [{				"metadata": {					"device_sn": "A4100000",					"device_name": "A4100000",					"port_number": 1,					"sensor_sn": "A4100000",					"sensor_name": "ATMOS 41W",					"units": " mph",					"errors": [						"ORIENTATION_ERROR",						"CURATED_RAIN_DEGRADED"					]				},				"readings": [					{						"timestamp_utc": 1756386000,						"datetime": "2022-02-12 07:00:00-06:00",						"tz_offset": -21600,						"value": null,						"precision": 2,						"mrid": 1110,						"error_flag": true,						"error_description": "Sensor is reporting an error"					},                    .....
```

In this example, the wind speed value is unavailable `null`, and the error\_flag value is set to `true`. The metadata.errors array lists an `ORIENTATION_ERROR` which could be the cause of the null value if the instrument is not level.

* * *

#### Location History

When the **Location** parameter is set to `true`, the API will return the logger's latitude and longitude history.

##### Example

```json
"location_history": [		{			"Latitude": 43.1122334,			"Longitude": -102.112233,			"Altitude": 654321.0,			"datetime": "2025-09-10 06:15:53.084519+00:00"		},		{			"Latitude": 30.1122334,			"Longitude": -101.112233,			"Altitude": 765432.0,			"datetime": "2024-09-10 06:00:36.632783+00:00"		},		{			"Latitude": 22.1122334,			"Longitude": -100.112233,			"Altitude": 876543.0,			"datetime": "2023-09-10 16:15:47.251351+00:00"		},    ]}
```

In this example, the device location history has three separate recorded locations.
