Local Energy History API for kWh Readings

Introduction What the Energy History API Provides Why Half-Hour kWh History Matters Supported Channel Layouts Single Phase Split Phase Three Phase Three Phase with Net Metering Enabled Original API Return Examples Empty Response Example Data Response Example Using the Return Values in Software Mapping channels to values Calculating a Half-Hour kWh Change Important Sampling Behavior Example Integration Ideas How This Fits Into Energy Management FAQ Can this API replace long-term energy history? Why is Datas empty after boot? Are timestamps based on local time? How should software interpret the values array?

Introduction

For users who build their own dashboards, automations, or offline analysis tools, real energy data is more useful when it is available at a stable interval. A single real-time power reading can show what is happening now, but half-hour kWh history helps users understand how electricity import and export change over time.

Starting from firmware version i.91.063TS8.bin, released on June 2, 2026, IAMMETER supports a new local API: GET /api/energyhistory. This API returns locally cached kWh readings sampled around UTC half-hour boundaries, making it easier to analyze recent energy usage without relying only on cloud-side history.

This is especially useful for solar monitoring, home energy monitoring, and custom energy management workflows where users want to compare import, export, and phase-level energy data. IAMMETER is not only a monitor; the purpose of collecting this data is to help users optimize energy use, improve solar self-consumption, and reduce electricity bills.

What the Energy History API Provides

The new endpoint is:

GET /api/energyhistory

It returns energy readings in kWh, sampled around these UTC half-hour boundaries:

00:00
00:30
01:00
01:30
and so on

The firmware keeps up to 96 records, equal to 48 hours of history at 30-minute intervals. The records are stored in the Wi-Fi module RAM, so they are lost after the device reboots.

A typical response includes:

utc: the current module UTC timestamp
timeSynced: whether the module has valid UTC time
interval: the sampling interval, currently 1800 seconds
count: the number of available history records
order: currently newest_first
unit: currently kWh
channels: the channel names matching each value
Datas: the half-hour history records

Each item in Datas includes a UTC timestamp and an array of kWh values. The values follow the same order as the channels array.

Why Half-Hour kWh History Matters

Half-hour energy data is practical because it gives users a compact but meaningful view of energy behavior. Instead of storing every real-time point, users can analyze accumulated import and export values over fixed time slots.

For example, a user can use the local data to:

Review recent imported and exported energy without waiting for cloud reports.
Export the latest 48 hours of kWh readings to a local database or CSV file.
Compare solar export patterns against household consumption.
Check whether an automation strategy changes electricity usage during specific periods.
Build a local dashboard for recent energy history.

For broader solar monitoring scenarios, see the IAMMETER Solar Energy Monitoring Solution. For residential electricity monitoring, see the IAMMETER Home Energy Monitoring Solution.

Supported Channel Layouts

The channels field tells the client how to interpret the values in each history record. Different meter configurations return different channel layouts.

Single Phase

["imp", "exp"]

Split Phase

["a_imp", "a_exp", "b_imp", "b_exp"]

Three Phase

["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp"]

Three Phase with Net Metering Enabled

["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp", "nem_imp", "nem_exp"]

Because the channel names are returned in the response, custom software should read the channels array first and then map each value in Datas[].values accordingly.

Original API Return Examples

The following two examples show the original API return values for an empty response and a data response.

Empty Response Example

After the device boots, the history array may be empty until valid UTC time and valid meter frames are available. In this case, the API can return count: 0 and an empty Datas array.

{
  "utc": 1780023600,
  "timeSynced": 1,
  "interval": 1800,
  "count": 0,
  "order": "newest_first",
  "unit": "kWh",
  "source": "wifi",
  "channels": ["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp"],
  "Datas": []
}

This response is normal after boot. A local dashboard or script should handle this state and wait for new half-hour samples.

Data Response Example

The following example shows two half-hour records from a three-phase meter. The response is ordered from newest to oldest.

{
  "utc": 1780023700,
  "timeSynced": 1,
  "interval": 1800,
  "count": 2,
  "order": "newest_first",
  "unit": "kWh",
  "source": "wifi",
  "channels": ["a_imp", "a_exp", "b_imp", "b_exp", "c_imp", "c_exp"],
  "Datas": [
    {
      "utc": 1780023600,
      "values": [11.337, 11.201, 11.039, 10.908, 10.975, 10.846]
    },
    {
      "utc": 1780021800,
      "values": [11.330, 11.198, 11.030, 10.900, 10.970, 10.840]
    }
  ]
}

In the newest record, a_imp is 11.337 kWh, a_exp is 11.201 kWh, and so on. The meaning of each value is defined by the channels array.

Using the Return Values in Software

The original return examples above are enough to build simple local analysis logic. The key is to read channels first, then apply that order to each item in Datas.

Mapping `channels` to `values`

When building software around this API, avoid hard-coding positions unless the meter configuration is fixed. A safer approach is to convert the channel list and value array into a named object.

const response = await fetch("http://<meter-ip>/api/energyhistory").then((res) => res.json());
const latest = response.Datas[0];

const latestByChannel = Object.fromEntries(
  response.channels.map((name, index) => [name, latest.values[index]])
);

console.log(latest.utc, latestByChannel);

For the sample three-phase response above, latestByChannel would contain:

{
  "a_imp": 11.337,
  "a_exp": 11.201,
  "b_imp": 11.039,
  "b_exp": 10.908,
  "c_imp": 10.975,
  "c_exp": 10.846
}

This makes the data easier to store, display, or export to a local analysis tool.

Calculating a Half-Hour kWh Change

If you use the returned kWh values as accumulated energy readings, the change between two adjacent records can be calculated by subtracting the older value from the newer value for the same channel.

Using the three-phase example above:

a_imp change = 11.337 - 11.330 = 0.007 kWh
a_exp change = 11.201 - 11.198 = 0.003 kWh
b_imp change = 11.039 - 11.030 = 0.009 kWh
b_exp change = 10.908 - 10.900 = 0.008 kWh

This kind of calculation can help users build a recent import/export report, compare phase-level energy changes, or check how much energy was imported or exported during a specific half-hour slot.

Important Sampling Behavior

The energy history is generated locally by the Wi-Fi module. The sampling behavior is important when building integrations or analysis tools:

Sampling is driven by valid UART meter frames.
The module stores the sample closest to each half-hour UTC boundary.
UTC time must be valid before history records are stored.
If timeSynced is 0, no new history samples are recorded.
After boot, Datas may be empty until enough valid samples have been captured.
Current storage is RAM-based, so the API is intended for recent local history, not long-term storage.

This makes the API suitable for local polling, short-term analysis, and integration testing. For long-term energy reports, users should still keep a persistent data source, such as IAMMETER cloud data or their own database.

Example Integration Ideas

Developers and advanced users can use /api/energyhistory as a simple local data source for recent kWh history.

One common approach is to poll the endpoint periodically, read the channels list, and save any new Datas records to a local database. This can support local dashboards, custom reports, or offline analysis scripts.

Another useful scenario is solar self-consumption analysis. By comparing imported and exported kWh values across half-hour slots, users can better understand when household loads consume solar generation locally and when surplus energy is exported. This can support better automation decisions, such as shifting flexible loads to periods with higher solar output.

If you are building local integrations, also see Local API, Modbus/TCP and MQTT and the IAMMETER Local API Explorer.

How This Fits Into Energy Management

The value of an energy history API is not only that it exposes more data. The key point is what users can do with that data.

With half-hour kWh history, users can analyze recent electricity import and export, identify usage patterns, and evaluate whether solar or load-control strategies are actually helping. This supports the broader IAMMETER goal: turning energy monitoring data into practical decisions that improve energy efficiency and reduce electricity bills.

For users who combine IAMMETER with automation platforms, local energy history can also provide a convenient data layer for testing and validating control logic. For example, Home Assistant users who optimize solar surplus usage can review recent kWh changes alongside automation behavior. See Home Assistant Solar Energy Automation with IAMMETER for a related use case.

FAQ

Can this API replace long-term energy history?

No. The API stores up to 96 records, or 48 hours of half-hour data, in RAM. It is designed for recent local history. The data is lost after reboot.

Why is `Datas` empty after boot?

After boot, the module needs valid UTC time and valid meter frames before history samples can be recorded. Until enough valid samples are captured, the API may return an empty Datas array.

Are timestamps based on local time?

No. The sampling slots are aligned to UTC half-hour boundaries.

How should software interpret the values array?

Always read the channels field first. The values in each Datas[].values array follow the same order as the channel names.