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

# Telemetry

> The two feeds VPP programs require: device state and device meter records.

VPP programs need to see what a device is doing and prove what it delivered, and two feeds carry that.

| Feed | What it is | Required when |
| :- | :- | :- |
| Device state | What the device is doing now | The device is enrolled |
| Device meter records | Energy the device moved, per interval | The device is enrolled, or the tariff is tiered |

The `telemetry` group on the [device](/docs/energy-api/reference/devices/retrieve.md) says which feeds are required, at what interval, and whether each is delayed. Intervals go down to 60 seconds. `device.update` fires when the group changes, so switch your pipelines per device from it.

Meter records use the same endpoints and formats as for tariffs. See [Meter records](/docs/energy-api/guides/tariffs/meter-records.md).

## Device state

Submit with [submit a device state](/docs/energy-api/reference/device-state/submit.md), or for up to 1,000 devices with [submit device states](/docs/energy-api/reference/device-state/submit-batch.md). The batch validates each sample alone and lists failures in `rejected`.

A sample is due when both are true:

* `telemetry.state_interval_seconds` has elapsed since your last submission.
* A signal changed: state of charge by 1 point, power by 0.1 kW, or any boolean, enum or timestamp.

While nothing changes, send a heartbeat every `telemetry.state_resend_interval_seconds`, which keeps `state_data_delayed` clear. Flatpeak sets it at three times the state interval, and never below 300 seconds.

Flatpeak shares state with the device's VPP operator and uses it to bound the device's share of VPP events.

## Device meter records

Every program settles on the device's own meter records, so every enrolled device submits them, at least as finely as `telemetry.device_meter_interval_seconds`. Use [submit device meter records](/docs/energy-api/reference/meter-records/submit-device.md).

## Location meter records

No VPP program requires location meter records. Flatpeak still uses them for [costs](/docs/energy-api/guides/tariffs/meter-records.md), and shares them with the device's VPP operator.

Location records come from the location's metering device: the one that measures the grid connection point, such as a storage gateway with a CT clamp.

* Declare it with `capabilities.metering.location` set to `true`. A location has one metering device.
* Submit with [submit location meter records](/docs/energy-api/reference/meter-records/submit-location.md), passing the metering device's `device_id`.
* Never send the same records on the device feed, because they would be counted twice.
* If two devices declare the capability, or submit for the same window, the last write wins. `metering.conflict` on the location turns `true` and `location.update` fires. Set `metering.location` to `false` on one.

## Sampling interval

Set the finest sampling interval your fleet sustains in the [Console](https://console.flatpeak.com) under account settings. Connect does not offer programs that sample finer.

Sampling and delivery are separate: sample at the required interval, then stream or batch the samples as suits your pipeline.


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