Home Assistant's built-in History and Logbook pages are useful for a quick check, but the default recorder only keeps a rolling window of data — typically 10 days — before older records are purged to keep the database small. If you want to see how your living room temperature trended over the last six months, compare this winter's heating usage to last winter's, or build a dashboard that actually looks like something out of a data centre, you need a proper time-series database and a dedicated visualisation tool. That combination is InfluxDB for storage and Grafana for dashboards, and both are available as official add-ons for Home Assistant OS and Supervised installs.
This guide covers installing both add-ons, configuring the influxdb: integration in Home Assistant's YAML, connecting Grafana to InfluxDB as a data source, and building your first panel.
What InfluxDB and Grafana Actually Do
InfluxDB is a time-series database. Unlike Home Assistant's default SQLite recorder, it is built specifically to store huge volumes of timestamped numeric data — exactly what sensor readings are — and query it efficiently over long ranges. It does not replace Home Assistant's recorder; it runs alongside it. Home Assistant keeps its short-term recorder for the History and Logbook UI, while the influxdb: integration streams a copy of your state changes into InfluxDB for permanent storage.
Grafana is a visualisation and dashboarding tool. It connects to InfluxDB (and dozens of other data sources) and lets you build custom graphs, gauges, tables, and alert rules from the stored data. It is not a Home Assistant product — it is a general-purpose open-source tool used widely in server monitoring and IoT — but it integrates cleanly with Home Assistant's InfluxDB export.
What You Need
- A running Home Assistant OS or Supervised installation (the add-on store is not available on Home Assistant Container or Core installs — you would need to run InfluxDB and Grafana as separate Docker containers instead).
- The Home Assistant Community Add-ons repository added to your add-on store. Most users already have this from installing other add-ons; if not, add
https://github.com/hassio-addons/repositoryunder Settings → Add-ons → Add-on Store → Repositories. - Basic familiarity with editing YAML, either through Settings → Add-ons → File editor or via Studio Code Server.
Step 1: Install the InfluxDB Add-on
Go to Settings → Add-ons → Add-on Store, search for InfluxDB, and select the add-on published under the Home Assistant Community Add-ons repository. Click Install and wait for it to finish — the add-on ships InfluxDB itself along with Chronograf and Kapacitor for optional database administration.
Once installed, open the add-on's Configuration tab. The default settings create an admin user and a database/organisation on first boot — note whichever credentials you set, since you'll need them for both the Home Assistant integration and the Grafana data source. Start the add-on and enable Start on boot and Watchdog so it comes back up automatically after a Home Assistant restart.
Step 2: Configure the InfluxDB Integration in Home Assistant
The Home Assistant side is configured through the influxdb: key in configuration.yaml — this integration is YAML-only for its filtering options, though basic connection fields can also be set through Settings → Devices & Services → Add Integration → InfluxDB. Home Assistant's InfluxDB integration supports InfluxDB 1.x, 2.x, and 3.x; the config keys differ slightly by version. For InfluxDB 2.x (the version the add-on installs by default), your configuration looks like this:
influxdb:
api_version: 2
host: a0d7b954-influxdb
ssl: false
port: 8086
token: !secret influxdb_token
organization: home
bucket: home_assistant
include:
domains:
- sensor
- binary_sensor
- climate
entity_globs:
- light.*
exclude:
entities:
- sensor.date
- sensor.timeA few notes on the fields that trip people up. host is the add-on's internal hostname (visible on the add-on's Info tab, usually in the form <hash>-influxdb) rather than an IP address, since Home Assistant and the add-on run on the same Supervisor network. token should be generated from the InfluxDB UI or Chronograf with write access to your bucket, and stored in secrets.yaml rather than hard-coded. The include/exclude block is optional but strongly recommended — without it, every entity in your system streams to InfluxDB, including diagnostic and configuration entities you almost certainly don't want charted. The integration matches an explicit entity list first, then domains, then glob patterns, so you can be as broad or as precise as you like.
If you're on InfluxDB 1.x instead (some older or self-hosted setups), the block uses database, username, and password in place of token, organization, and bucket — and the 1.x database must be created manually before Home Assistant will write to it.
Save the file and restart Home Assistant. If the connection is working, you'll see state changes for your included entities start appearing in InfluxDB within a minute or two — you can verify this from the InfluxDB add-on's Chronograf interface, or by checking the Home Assistant log for any influxdb connection errors.
Step 3: Install the Grafana Add-on
Back in the Add-on Store, search for Grafana and install the Home Assistant Community Add-ons version. Start it, enable Show in sidebar, and open it from the Home Assistant sidebar or directly at port 3000 on your Home Assistant host. Log in with the default admin/admin credentials. On the Home Assistant add-on build, the default admin password can't be changed directly from the UI, so the recommended approach is to create a new user with the Admin role from Grafana's user settings and then delete the original default admin account.
Step 4: Connect Grafana to InfluxDB
Inside Grafana, go to Connections → Add new connection, search for InfluxDB, and select it. On the setup screen, choose Flux as the query language (this is the query language InfluxDB 2.x and 3.x use) and fill in:
- URL — the InfluxDB add-on's address and port, e.g.
http://a0d7b954-influxdb:8086 - Organization — the same organisation name used in your
influxdb:config (e.g.home) - Token — the same InfluxDB API token, with at least read access
- Default Bucket — the bucket name (e.g.
home_assistant)
Click Save & test. A working connection reports back the number of buckets found in your InfluxDB instance. If it fails, the most common causes are a mismatched token, the wrong internal hostname, or the organisation name not matching exactly what's set in the InfluxDB add-on.
Step 5: Build Your First Dashboard Panel
From the Grafana sidebar, go to Dashboards → New → New Dashboard → Add visualization, and select your InfluxDB data source. Switch to the Flux query editor and write a query against your bucket, filtering by entity ID. A basic query to chart a temperature sensor over the last seven days looks like:
from(bucket: "home_assistant")
|> range(start: -7d)
|> filter(fn: (r) => r["_measurement"] == "°C")
|> filter(fn: (r) => r["entity_id"] == "living_room_temperature")
|> filter(fn: (r) => r["_field"] == "value")Note that the _measurement value in InfluxDB corresponds to whatever the integration used as the measurement name — by default this is the entity's unit of measurement (controlled by the measurement_attr option), so a temperature sensor typically lands under a measurement named after its unit rather than its entity ID. Set the panel type to Time series, give it a title, and Grafana renders a line graph updating live as new data streams in from Home Assistant.
From here, repeat the process for other entities — humidity, energy consumption, or anything else you included in the influxdb: filter — and arrange the panels into a dashboard. Grafana panels can also be pinned as a full dashboard link in Home Assistant's own Lovelace dashboard using an iframe or webpage card, so you don't need to switch apps to check your long-term history.
Common Problems and Fixes
No data appears in InfluxDB. Check the Home Assistant log for connection errors first — a wrong host or token is the most common cause. Confirm the entity you're checking for isn't accidentally caught by an exclude filter, and that InfluxDB and Home Assistant are both running.
Grafana shows the data source is fine but the panel is empty. This is almost always a mismatched _measurement or entity_id filter in the Flux query — use Chronograf (bundled with the InfluxDB add-on) to browse your actual measurement and tag names rather than guessing.
Restarting Home Assistant loses the connection temporarily. This is expected — the integration reconnects automatically once Home Assistant finishes starting, and any missed writes during the restart simply aren't recorded (InfluxDB doesn't backfill).
Is It Worth Setting Up?
For most casual users, Home Assistant's default 10-day recorder and the built-in Energy dashboard are enough. InfluxDB and Grafana earn their keep once you want year-over-year comparisons, custom alerting thresholds Grafana can email or Slack you about, or dashboards that combine Home Assistant data with other sources entirely — server metrics, network throughput, or a solar generation feed, for example. It's a bigger commitment than a stock Lovelace dashboard, but for anyone running Home Assistant as a serious home-data project rather than just light switches, it's one of the most useful additions you can make.
