Get aggregated statistics for a time range
statistics_get_statisticsRetrieve aggregated recorder statistics for specified IDs over a time range to analyze energy, temperature, or other trends across hours, days, weeks, or months.
Instructions
Get aggregated recorder statistics for one or more IDs over a time range.
Calls WS recorder/statistics_during_period with start/end parsed
into UTC timestamps, converts each row's epoch start back to an ISO
string, and rounds numeric aggregates to 4 decimals.
Use when: analysing energy/temperature/etc. trends over hours, days,
weeks or months using the recorder's pre-aggregated data.
Not for: raw short-term state changes between two points in time — use
history_get_state_history instead.
Returns: {"period", "start", "end", "types", "data": {statistic_id: [{"start": <iso>, "sum": ..., "mean": ..., ...}, ...]}}.
Errors: {"error": "..."} for an empty statistic_ids, an invalid
period/types value, an unparsable start/end, a non-dict WS
response, or when the WS call raises.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | End of the range, same formats as `start`. Omit to use the current time. | |
| start | Yes | Start of the range: a date ('2024-01-01') or datetime ('2024-01-01T00:00:00'). | |
| types | No | Which aggregates to include per bucket, any of 'sum', 'mean', 'min', 'max', 'state', 'change'. Omit to use ['sum', 'mean', 'min', 'max']. | |
| period | No | Aggregation bucket size: one of '5minute', 'hour', 'day', 'week', 'month'. | day |
| statistic_ids | Yes | Entity or statistic IDs to fetch, e.g. ['sensor.energy_consumption']. Discover valid values with `statistics_list_statistic_ids`. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||