How to read the numbers the API returns, how fresh they are and how often it makes sense to ask for them.
Units
| Quantity | Unit | Type |
|---|---|---|
| Power | W | integer |
| Energy | Wh | integer, always ≥ 0 |
| State of charge | % | number, 0–100 |
Signs
Grid and battery power carry a sign:
| Field | Positive | Negative |
|---|---|---|
grid_power_w |
import from the grid | export to the grid |
battery_power_w |
battery charging | battery discharging |
Energy values, instead, are never negative: the direction is in the field name (imported / exported, charged / discharged).
Timestamps
- Telemetry, connectivity and alarm timestamps are ISO 8601 in UTC (
2026-10-13T12:21:00Z). - Energy windows (
period_start,period_end,timestamp_start,timestamp_end) are ISO 8601 in the plant's time zone, with its offset (2026-10-13T00:00:00+02:00). - State of charge is per gateway, never a plant average.
How often data is updated
| Data | How it is produced | Practical consequence |
|---|---|---|
| Power | one sample per gateway every 60 s | polling more often returns the same sample |
| Online status | data received in the last 5 minutes | a plant goes offline 5 minutes after its last sample |
| Energy | 15-minute counters | today's totals trail real time by about 15 minutes |
The null rule on telemetry/latest
telemetry/latest returns samples of the last 5 minutes only. When the plant sent no data in that time, the response is still 200, with "timestamp": null and "measurements": null: an old value is never returned. A null therefore means "no recent data", not "zero"; to see since when the plant has been silent, check last_seen_at in the connectivity.
Inside measurements, pv_power_w and load_power_w read 0 on plants that do not measure them; they are null only in telemetry/series samples. Always handle null as a possible value for power, state of charge and energy.
Recommended polling
Pattern for a fleet of up to 100 plants, that is one bulk page:
| Call | Interval | Requests per day |
|---|---|---|
GET /v1/telemetry/latest |
60 s | 1 440 |
GET /v1/connectivity |
5 min | 288 |
GET /v1/energy/totals?period=day |
15 min | 96 |
| Total | ≈ 1 800 |
- Shorter intervals do not give fresher data: they return the same samples.
- Read power series, energy series and alarms per plant only when you need them.
- Each extra bulk page multiplies the requests: beyond 100 plants this pattern exceeds the daily limit (see "Limits, errors and support"), so lengthen the intervals or ask for a dedicated agreement.