> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kapa.energy/llms.txt
> Use this file to discover all available pages before exploring further.

# Data and telemetry

> Read battery measurements and receive telemetry events.

Read telemetry history or the latest measurement for a battery. The latest response
has a `null` point if Kapa has not received a measurement yet.

## Measurements

* Each data point carries two times: `measured_at`, when the device took the
  measurement, and `received_at`, when Kapa retrieved it from the manufacturer's cloud.
* Data points are never interpolated or resampled. Each point is an actual
  measurement reported by the manufacturer. Units, signs and field names are
  standardised across manufacturers; a field the manufacturer does not report is `null`.

## Time conventions

* Timestamps are RFC 3339, in UTC, with a `Z` suffix: `2026-11-12T18:00:00Z`.
* Durations are ISO 8601: `PT15M`.
* Time windows are half-open, `[start, end)`: `start` is included, `end` is excluded.

## Power

Power is in watts (W), as integers.

* **Positive (+)**: the battery is discharging, or the site is exporting to the grid.
* **Negative (−)**: the battery is charging, or the site is importing from the grid.

Nominal ratings such as `nominal_charge_power_w` are magnitudes and are always positive.

## Energy

Energy is in watt-hours (Wh), as integers. Battery levels are expressed as stored
energy in Wh rather than state of charge in %, because the meaning of SoC differs
between manufacturers. Stored energy is measured against the usable capacity: it
ranges from 0 to `usable_capacity_wh`.

## Telemetry events

Receive [new telemetry points](https://docs.kapa.energy/webhooks/telemetry.md) at your HTTPS endpoint. Delivery
is at least once and not ordered. Deduplicate with `event_id` and order data with
`measured_at`. Webhook registration is not covered by this version of the API.

## Errors

Errors use RFC 9457 Problem Details (`application/problem+json`). The `code` field is
stable and meant for programs; `title` and `detail` are meant for humans.

| `code` | HTTP | Meaning |
| - | - | - |
| `invalid_parameters` | 400 | A parameter is missing, malformed or inconsistent (e.g. `min_wh` greater than `max_wh`). |
| `invalid_time_window` | 400 | `start` is not before `end`, or `end` is in the past. |
| `unauthorized` | 401 | The access token is missing, invalid or expired. |
| `battery_not_found` | 404 | No battery with this id is accessible to the client. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.