How do I install the Ha Statistics skill?

Run npx skillmds@latest add beclab/ha-statistics in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Ha Statistics safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Ha Statistics?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Ha Statistics free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Ha Statistics?

beclab (@beclab) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Ha Statistics by beclab — Agent Skill

Name: Ha Statistics
Author: beclab

Ha Statistics

Query Home Assistant's recorder long-term statistics with hass-cli: list which statistic ids exist, read their metadata (unit, source, has_sum/has_mean), and pull aggregated values (sum/mean/min/max) over a time period and bucket. Use for 'how much energy/water/gas over time', 'trend of this sensor', 'monthly totals', or as the data source for consumption/audit analyses. Distinct from instantaneous state history.

beclab cd472f6 2.4 KB Updated Sep 17, 2026

File contents

ha-statistics

Recorder long-term statistics — the aggregated, downsampled history HA keeps for sensors with state_class (and external stats). Prerequisite: ../ha-shared/SKILL.md.

Statistics vs. history

History (hass-cli system history) = raw state changes, short retention.
Statistics (here) = hourly/daily/.. roll-ups (sum/mean/min/max), kept long-term. Use these for "totals over a month", energy, trends.

Discover what exists

hass-cli statistics info                      # recorder health (backlog, running)
hass-cli statistics list                      # all statistic ids + metadata
hass-cli statistics list --type sum           # only cumulative (energy/water/gas)
hass-cli statistics list --type mean          # only averaged (temperature, power)
hass-cli statistics metadata --ids sensor.a,sensor.b

list entries carry statistic_id, unit_of_measurement, source, has_sum, has_mean.

Pull values over a period

hass-cli statistics period \
  --ids sensor.energy_total,sensor.water_total \
  --start 2026-06-01T00:00:00+00:00 \
  --end   2026-06-30T23:59:59+00:00 \
  --period day

--period bucket: 5minute|hour|day|week|month (default hour).
--start is required (ISO8601); --end defaults to now.
Result maps each id to an array of buckets. sum series are cumulative — for "how much in June", subtract the first bucket's sum from the last (or read change when present). mean series give the average per bucket.

Notes

A fresh instance has empty statistics until the recorder accrues data (first roll-up after ~1 hour); list may return [] initially.
Combine with ../ha-energy/SKILL.md: take the stat_* ids from energy prefs get, then query them here.
Audits (e.g. "dead/never-updating statistics") are derived client-side from this native data — not a built-in HA feature.

---name: ha-statisticsdescription: Query Home Assistant's recorder long-term statistics with hass-cli: list which statistic ids exist, read their metadata (unit, source, has_sum/has_mean), and pull aggregated values (sum/mean/min/max) over a time period and bucket. Use for 'how much energy/water/gas over time', 'trend of this sensor', 'monthly totals', or as the data source for consumption/audit analyses. Distinct from instantaneous state history.---# ha-statisticsRecorder long-term statistics — the aggregated, downsampled history HA keepsfor `sensor`s with `state_class` (and external stats). **Prerequisite:**[`../ha-shared/SKILL.md`](../ha-shared/SKILL.md).## Statistics vs. history- **History** (`hass-cli system history`) = raw state changes, short retention.- **Statistics** (here) = hourly/daily/.. roll-ups (`sum`/`mean`/`min`/`max`), kept long-term. Use these for "totals over a month", energy, trends.## Discover what exists```bashhass-cli statistics info # recorder health (backlog, running)hass-cli statistics list # all statistic ids + metadatahass-cli statistics list --type sum # only cumulative (energy/water/gas)hass-cli statistics list --type mean # only averaged (temperature, power)hass-cli statistics metadata --ids sensor.a,sensor.b````list` entries carry `statistic_id`, `unit_of_measurement`, `source`,`has_sum`, `has_mean`.## Pull values over a period```bashhass-cli statistics period \ --ids sensor.energy_total,sensor.water_total \ --start 2026-06-01T00:00:00+00:00 \ --end 2026-06-30T23:59:59+00:00 \ --period day```- `--period` bucket: `5minute|hour|day|week|month` (default `hour`).- `--start` is required (ISO8601); `--end` defaults to now.- Result maps each id to an array of buckets. `sum` series are cumulative — for "how much in June", subtract the first bucket's `sum` from the last (or read `change` when present). `mean` series give the average per bucket.## Notes- A fresh instance has empty statistics until the recorder accrues data (first roll-up after ~1 hour); `list` may return `[]` initially.- Combine with [`../ha-energy/SKILL.md`](../ha-energy/SKILL.md): take the `stat_*` ids from `energy prefs get`, then query them here.- Audits (e.g. "dead/never-updating statistics") are derived client-side from this native data — not a built-in HA feature.

Frequently asked questions