Home Assistant’s recorder keeps detailed state history for 10 days by default, and long-term statistics last longer. If you want raw sensor history for longer, or charts that Home Assistant’s built-in graphs can’t show, you can send sensor data to InfluxDB and chart it in Grafana. This guide covers the setup, the filters that keep the database manageable and a few starter queries.
What Home Assistant already keeps
- Recorder history. The recorder stores full state history for 10 days by default. You can change this with
purge_keep_daysin the recorder settings. - Long-term statistics. Hourly means, minimums, maximums or sums are kept for entities that have a state class. They persist beyond the 10-day window.
- InfluxDB is not a replacement. It only receives data from the moment you set it up, and it doesn’t import earlier recorder history. Home Assistant’s history and energy views still use the recorder.
Choose an InfluxDB version
| Version | What Home Assistant needs | Query language |
|---|---|---|
| InfluxDB 1.x | Database, and a username and password if authentication is on | InfluxQL |
| InfluxDB 2.x | Organization, bucket and a token with write access | Flux, or InfluxQL through DBRP mapping |
| InfluxDB 3 | Depends on the integration’s current support | SQL or InfluxQL |
Check the Home Assistant InfluxDB documentation for the versions it supports today. InfluxDB 3 offers v1 and v2-compatible write APIs, but compatibility varies. Choose a version the documentation supports, and pick the query language you’re willing to learn.
Install InfluxDB and Grafana
Community add-ons exist for InfluxDB and Grafana on Home Assistant OS. You can also run both as containers on another machine. The default ports are 8086 for InfluxDB and 3000 for Grafana.
Put the database on an SSD rather than an SD card. A database writes continuously, and that wears out SD cards faster.
Connect Home Assistant to InfluxDB
Go to Settings > Devices & services, add the InfluxDB integration and enter the connection details for your version. Keep SSL verification on. If your server uses a self-signed certificate, provide its CA certificate rather than turning verification off.
Filters are set in configuration.yaml, so you control what gets written. Restart Home Assistant after you change them.
influxdb:
include:
domains:
- sensor
- binary_sensor
- climate
exclude:
entities:
- sensor.noisy_example
Filter aggressively. Writing every entity makes the database larger and fills it with noise from sensors that change often.
By default, the measurement name is the unit of measurement, such as °C, W or %. The entity ID without its domain becomes the entity_id tag, and the state is stored in the value field. The measurement_attr option changes how measurements are named, if the default doesn’t suit your queries.
Confirm that data is arriving
Check InfluxDB before you build any dashboards. Pick one sensor that isn’t critical, then query for it. For a 1.x database, this InfluxQL query returns the last hour of readings from sensors that report in °C:
SELECT * FROM "°C" WHERE time > now() - 1h
If nothing shows up, check the include and exclude filters, the token or user permissions, and the database or bucket name. The Home Assistant log also shows write errors.
Connect Grafana
In Grafana, go to Connections, select Add new connection and choose InfluxDB. Then add the data source. Enter the URL, such as http://<influx-host>:8086, and choose the product and query language that match your database. Fill in the fields for that language:
- InfluxQL: database, user and password.
- Flux: organization, default bucket and a token with read access.
- SQL: database and token.
Click Save & test before you build any panels.
Use separate, read-only credentials for Grafana. Home Assistant needs write access, and Grafana only needs to read.
Starter queries
This InfluxQL panel query shows the mean value of one sensor over time:
SELECT mean("value") FROM "°C"
WHERE "entity_id" = 'living_room_temperature' AND $timeFilter
GROUP BY time($__interval)
The same idea in Flux:
from(bucket: v.defaultBucket)
|> range(start: v.timeRangeStart, stop: v.timeRangeStop)
|> filter(fn: (r) => r["_measurement"] == "°C")
|> filter(fn: (r) => r["entity_id"] == "living_room_temperature")
|> filter(fn: (r) => r["_field"] == "value")
|> aggregateWindow(every: v.windowPeriod, fn: mean)
Replace living_room_temperature with your sensor’s entity ID, without the domain. Use GROUP BY time or aggregateWindow on long time ranges. Without aggregation, a query can return a very large number of points, and the panel becomes slow.
Keep the database manageable
Retention policies and downsampling let you keep detailed data for a short period and summaries for longer. For example, you might keep raw data for 30 days and five-minute means after that. InfluxDB 1.x does this with retention policies and continuous queries. InfluxDB 2.x uses tasks.
Show Grafana on your dashboard
To place a Grafana panel in Home Assistant, use a webpage or iframe card. Grafana must allow embedding, which is set with allow_embedding = true in its configuration. Some setups also need anonymous access. That exposes the dashboard to anyone who can reach the page, so use a Grafana login where you can, and keep embedded dashboards on a private network.
Troubleshooting
- No points in InfluxDB. Check the include and exclude filters, the token or user’s write permission, and the database name.
- An empty panel. Check the time range, the measurement name and the
entity_idvalue. - Flux queries fail on InfluxDB 3. Flux isn’t supported there, so use InfluxQL or SQL.
- Slow panels on long ranges. Add aggregation, and check the timeout in the data source settings.
Common mistakes
- Thinking Home Assistant forgets everything after 10 days. Long-term statistics persist.
- Thinking InfluxDB replaces the recorder. It doesn’t. History and energy views still use the recorder.
- Logging every entity. Filter to the sensors you chart.
- Running the database on an SD card. Use an SSD.