Get Entity History or Statistics
ha_get_historyRetrieve past Home Assistant entity states or aggregated statistics to troubleshoot changes, analyze event sequences, and track long-term trends.
Instructions
Get historical data from Home Assistant's recorder.
Sources:
"history" (default): Raw state changes, ~10 day retention, full resolution
"statistics": Pre-aggregated data, permanent retention, requires state_class
Shared params: entity_ids, start_time, end_time, limit, offset History params: minimal_response, significant_changes_only Statistics params: period, statistic_types
Default time range: 24h for history, 30 days for statistics
Use ha_get_history (default) when:
Troubleshooting why a value changed ("Why was my bedroom cold last night?")
Checking event sequences ("Did my garage door open while I was away?")
Analyzing recent patterns ("What time does motion usually trigger?")
Use ha_get_history(source="statistics") when:
Tracking long-term trends beyond 10 days ("Energy use this month vs last month?")
Computing period averages ("Average living room temperature over 6 months?")
Entities must have state_class (measurement, total, total_increasing)
WARNING: limit and offset apply per entity (not globally across all entities). All data is fetched from HA before slicing; limit/offset are client-side. With multiple entity_ids, offset must be 0 — use a single entity_id for offset > 0. Use has_more and next_offset from the response to paginate. Administrators can optionally enable recorder workload guardrails in Advanced settings. When enabled, oversized entity/time workloads are rejected before the recorder query is issued; narrow the time range or entity list to stay within the budget. Calendar statistics may first read HA's configured timezone so the estimate follows local calendar boundaries.
Example -- history (default):
ha_get_history(entity_ids="sensor.bedroom_temperature", start_time="24h")
ha_get_history(entity_ids=["sensor.temperature", "sensor.humidity"], start_time="3d", limit=500)
# Default order="desc" returns newest states first.
# To paginate oldest-first, use order="asc":
ha_get_history(entity_ids="sensor.temperature", start_time="7d", limit=100, offset=100, order="asc")Example -- statistics:
ha_get_history(source="statistics", entity_ids="sensor.total_energy_kwh", start_time="30d", period="day")
ha_get_history(source="statistics", entity_ids="sensor.living_room_temperature",
start_time="6m", period="month", statistic_types=["mean", "min", "max"])
ha_get_history(source="statistics", entity_ids="sensor.energy_kwh",
start_time="30d", period="5minute", limit=100, offset=200)Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max entries per entity. Default: 100, Max: 1000. For source="history": state changes. For source="statistics": aggregated rows. With multiple entity_ids, offset must be 0 and total rows returned can reach limit × len(entity_ids). | |
| order | No | Sort order for history entries. "desc" (default): newest first. "asc": oldest first (chronological, as returned by HA API). Ignored when source="statistics". | desc |
| fields | No | Return only the specified top-level response keys to reduce response size. None = full response (default). History keys: success, source, entities, period, query_params. Statistics keys: success, source, entities, period_type, time_range, statistic_types, query_params, warnings. | |
| offset | No | Number of entries to skip per entity for pagination. Default: 0. Offset > 0 requires a single entity_id. Use with limit and has_more/next_offset in the response. | |
| period | No | Aggregation period: "5minute", "hour", "day", "week", "month", "year". Default: "day". Ignored when source="history" | day |
| source | No | Data source: "history" (default) for raw state changes (~10 day retention), or "statistics" for pre-aggregated long-term data (permanent, requires state_class). | history |
| end_time | No | End time: ISO datetime. Default: now | |
| entity_ids | Yes | Entity ID(s) to query. Can be a single ID, comma-separated string, or JSON array. | |
| start_time | No | Start time: ISO datetime or relative (e.g., '24h', '7d', '30d'). Default: 24h ago for history, 30d ago for statistics | |
| statistic_types | No | Statistics types: "mean", "min", "max", "sum", "state", "change". Default: all. Ignored when source="history" | |
| minimal_response | No | Return only states/timestamps without attributes. Default: true. Ignored when source="statistics" | |
| significant_changes_only | No | Filter to significant state changes only. Default: true. Ignored when source="statistics" |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||