Pull ZENTRA Cloud data into Google Sheets

Pull your ZENTRA Cloud data into Google Sheets

The ZENTRA Cloud Sheets template is a Google Sheets file with a script already built into it. Copy the template, paste in your API token, choose your devices and dates, and your readings arrive in the spreadsheet. There is nothing to install and no code to write.

What it does:

Creates one tab per device, with a column for every measurement that device reports.
Refreshes incrementally, so a later pull only fetches readings you do not already have.
Handles paging and ZENTRA Cloud’s rate limits for you.
Can refresh on a schedule, without the sheet being open.
Records every run on a Status tab.

If you prefer to work in code, or you need to move several years of history at once, the Python SDK zentracloud-py and the R client zentraR are better suited to that job.

Before you start

You need:

A ZENTRA Cloud account with at least one device.
A Google account.
A ZENTRA Cloud v5 API token (step 2 below).

Step 1 — Copy the template

Open the template link and select Make a copy.

The dialog asks “Would you like to make a copy of ZENTRA Cloud Apps Script Sheets Template?” and shows a yellow banner reading “The attached Apps Script file and functionality will also be copied”. That banner is expected — the attached script is the part that fetches your data.

The copy is a private spreadsheet in your own Google Drive. You own it, and you can rename, share and edit it like any other sheet.

Each copy is independent. Later improvements to the template do not reach copies that already exist. To pick up a newer version, copy the template again into a fresh sheet and pull your data into that one. Charts, formulas and notes you built on the old sheet do not carry across, so keep anything you want to reuse.

Step 2 — Get your API token

In ZENTRA Cloud, go to User Account → Integrations → Show Token and copy the token. You will paste it into the sheet in step 4.

Step 3 — Open the sidebar and authorize the script

In your copy of the sheet, open the ZENTRA Cloud menu and choose Setup and pull…

The first time you run it, Google asks you to authorize the script. This happens once per Google account.

On Authorization required — “A script attached to this document needs your permission to run.” — select OK.
Sign in with the Google account that owns the sheet.
Google then shows a red “Google hasn’t verified this app” page whose most prominent button is Back to safety. This is expected. The script is a copy running inside your own Drive rather than a published, verification-reviewed Google Workspace add-on, so Google has no verification record for it. To continue:
1. Select Advanced at the bottom left.
2. Select Go to ZENTRA Cloud Sheets by METER Group Inc. USA (unsafe).
Review the permissions, tick them, and select Continue.

The developer address on this page is your own Google account, not METER's. That is correct and expected. Copying the template forked the script into your own Drive, so the copy belongs to you and Google names you as its developer. The app name survives the copy, so the name — not the address — is what confirms you are authorizing the METER script.

Permission	Why the template needs it
View and manage spreadsheets that this application has been installed in	Write readings into this sheet — and only this sheet
Connect to an external service	Call the ZENTRA Cloud API
Allow this application to run when you are not present	Continue a long pull after you close the sheet, and run the scheduled refresh
Display and run third-party web content in prompts and sidebars inside Google applications	Draw the sidebar you work in

The ZENTRA Cloud sidebar then opens on the right.

Step 4 — Your first pull

1. Your API token

Paste the token into the box and select Save token. The sidebar confirms with “Token saved for this Google account.”

The token is validated against ZENTRA Cloud before it is stored, and it is kept with your Google account — not inside the spreadsheet. If you share the sheet with a colleague, they paste their own token; they never see yours.

2. Devices

Tick the devices you want. The list shows every device your token can reach, named <device name> (<serial>).

Some devices may appear greyed out and cannot be ticked. Hovering over one explains why: “Your account can see this device but cannot read its data.” Ask that device’s organization administrator for the User role or higher.

If devices were added or shared with you after you opened the sheet, select Reload device list.

3. Units and date range

Choose Metric (the default) or Imperial, set From and To, then select Pull.

Leave “Rebuild these tabs from scratch (slower; not needed for a normal refresh)” unticked for a normal pull. See Rebuilding a tab for when to use it.

Watching it run

The Progress box reports as it goes:

Pulling. This can take several minutes for long windows; you can close this panel and it will keep going.

You can close the sidebar, and even close the spreadsheet — the pull continues. When it finishes, the box shows a summary per device, for example:

Pull finished at 2026-09-15 19:25 UTC.A4100110 (A4100110): 1 of 1 months, 8 rows added A4100112 (A4100112): 1 of 1 months, 6 rows added

To stop a pull early, use Cancel pull in the Progress box or in the ZENTRA Cloud menu.

What lands in the sheet

One tab per device, named <device name> (<serial>) — for example A4100110 (A4100110). The (<serial>) part is how the template finds the tab again, so renaming a device in ZENTRA Cloud does not orphan its data. Long device names are shortened before the serial to fit Google’s 100-character tab-name limit.

A frozen header row. Column A is Timestamp (device local time). Every measurement column is named <measurement> (<unit>) · <sensor name> port <n>, with @ <position> added when the sensor reports one — for example Battery Percent (%) · Battery port 2.

Rows in ascending time order, oldest first.

An append-only column layout. New measurement columns are appended at the right; existing columns never move. Formulas, charts and pivot tables built on top of a tab keep pointing at the right data after a refresh.

A note on cell A1 carrying the last run’s result and a per-device summary, such as “3 of 13 months, 4,102 rows added” or “already up to date”. Hover over A1 to read it.

Columns you add yourself alongside the data are left alone by a refresh.

Reading the Status tab

The Status tab is the first tab in the sheet and is the place to look when something seems wrong.

Row	What it tells you
Schedule	Whether a scheduled refresh is on, how often it runs, and which Google account runs it
Units	Metric or Imperial
Times shown in	A reminder of which times are which: readings carry each device’s own local time and UTC offset, while the pull window dates and the times on this tab are UTC
Last successful update	When the last good run finished, and the account that ran it
Last failure	When the last failure happened, the account, and the reason
Current run	Whether a pull is running right now
Data may be stale	Appears only when the last refresh failed, or when a schedule has not run for more than two of its periods

The account names on this tab are visible to anyone who can view the sheet.

Refreshing

ZENTRA Cloud → Refresh now reuses the devices and date range from your last pull, so it is a one-click top-up. If nothing has been pulled yet it says:

Nothing to refresh yet. Use ZENTRA Cloud, Setup and pull… first.

To change devices, dates or units, use Setup and pull… instead.

Scheduled refresh

Section 4. Scheduled refresh in the sidebar keeps the sheet up to date without anyone opening it.

Choose Every hour, or Every day at a particular hour, then select Turn on. The sidebar confirms, for example: “Scheduled refresh is on: Daily at 08:00 America/Los_Angeles, run by name@example.com.” Turn off stops it.

Rules worth knowing:

It runs as the person who turned it on, using that person’s Google account and their API token. If they leave or remove their token, the schedule fails.
The daily hour follows the spreadsheet’s time zone (File → Settings → General). The sidebar and the Status tab both name the zone in use.
One schedule per sheet. If someone else has already turned it on, you are asked “This sheet’s schedule is run by <owner>. Replace it with a schedule run by your account?” and offered a Replace button.
The account running it is visible on the Status tab and in the sidebar to anyone who can view the sheet.
Failures are recorded, not hidden. If the token is gone or no devices are selected, the Status tab says so. If a pull is already running, the scheduled run skips that turn and says why.

Behavior to know

Interior gaps are not refilled

A refresh extends the data backwards from the earliest row and forwards from the latest one. It does not look for holes in between. So rows you deleted by hand, or readings a device uploaded late, are not picked up by a normal refresh.

Rebuilding a tab

To fill gaps, or to start a tab over, tick “Rebuild these tabs from scratch (slower; not needed for a normal refresh)” before pulling. The selected tabs are cleared and the whole date range is fetched again. Anything you built inside those tabs is cleared too.

Timestamps arrive as text

Each timestamp is written in the device’s own local ISO format, including its UTC offset, so the offset is never lost. Because of that, Sheets treats the cell as text. To chart against time, convert in a helper column:

=DATEVALUE(MID(A2,1,10))+TIMEVALUE(MID(A2,12,8))

Reading times and pull windows use different zones

Readings carry each device’s own local time and offset, but the From and To dates are read as UTC. On a device far from UTC, the first and last rows can sit a few hours outside the dates you chose.

Switching units rebuilds the tabs

Unit names are part of the column headers, so changing Units in sidebar section 3 between Metric and Imperial clears and re-pulls the selected device tabs. You are asked to confirm first:

Changing units clears and re-pulls the selected device tabs. Continue?

Select Continue to go ahead.

Long first pulls take a while — and can be interrupted

Readings are fetched in UTC calendar-month windows. A run pauses after roughly five minutes and restarts itself automatically, which is why the progress summary counts months. A consumer Google account allows about 90 minutes of this background runtime per day, so pull a year or two at a time rather than a decade at once. For a large history, the Python SDK or R client is the better tool.

Data older than about 2.5 years

ZENTRA Cloud does not retain readings older than roughly 2.5 years. A window that falls entirely before the earliest stored data reports that “the requested window is before the earliest data ZENTRA Cloud holds for this device”.

Rate limits

ZENTRA Cloud limits how often the API can be called. Each endpoint allows a burst of 5 requests and then refills at 1 request per minute; about 300 seconds idle restores the full burst.

Endpoint	Counted per	Burst	Steady state
List Devices (`GET /v5/devices`)	User, from the API key	5	1/min
Get Device Readings (`GET /v5/devices/{id}/data`)	Device	5	1/min

Readings are counted per device, not per caller. Everyone authorized for a device shares that device’s budget, so a wait the template reports may be caused by a colleague pulling the same device — not by anything wrong with your sheet.

The template handles this for you: when it is told to wait, it waits and then carries on.

Full details: Rate Limiting

Troubleshooting

What you see	What it means	What to do
“ZENTRA Cloud did not accept your API token. It may have been revoked or mistyped. Copy a fresh token from app.zentracloud.io…”	The token is wrong, or it has been revoked	Copy a fresh token from User Account → Integrations → Show Token and save it again
“Your account does not have access to this device’s data. Ask the device’s organization administrator to grant you the User role or higher.”	Your account can see the device but not read from it	Ask that device’s organization administrator for the User role or higher
A device reported as not found	The device was removed, or stopped being shared with you	Reload the device list and choose your devices again
A message naming a wait time	The rate limit was reached	Nothing — the template waits and continues. This is normal on long first pulls, and can also happen when other people pull the same device at the same time
“Could not reach ZENTRA Cloud. Check your internet connection and try again in a minute.”	Network problem between Google and ZENTRA Cloud	Check your connection and try again shortly
“ZENTRA Cloud had a temporary problem answering. Try again in a few minutes.”	ZENTRA Cloud returned a server error	Wait a few minutes and pull again
“The pull stopped after repeated errors. Use ZENTRA Cloud, Setup and pull to start it again.”	Too many failures in a row, so the run stopped	Fix the cause above, then start a new pull

Messages you may see while setting up a pull:

“Enter your API token first.”
“Select at least one device.”
“Enter both dates as YYYY-MM-DD.”
“The end date must be after the start date.”
“A pull is already running. Wait for it to finish, or use Cancel pull.”
“Reload the device list, then choose devices again.”

Removing your token

ZENTRA Cloud → Forget my token deletes the saved token from your Google account. It does not touch the data already in the sheet, and it does not affect anyone else’s token.