Leave InfluxDB, keep your Home Assistant history

Who this is for

Anyone whose Home Assistant sends its history to InfluxDB through the built-in influxdb integration — to the InfluxDB 1.x app inside Home Assistant, or to an InfluxDB 1.x or 2.x on another machine — and who would rather not run a database for it any more. If you have never used InfluxDB, this page is not for you: the Home Assistant integration guide is the whole setup.

What stays, what you gain, what you give up

Stays the same

• The integration doing the writing, if you like. Tag Historian speaks the InfluxDB v2 write API, so Home Assistant's own InfluxDB integration can keep writing, with the include filter in configuration.yaml exactly as it is. Or the Tag Historian integration takes over, with a picker in place of the filter — step 5 has both.
• The names. sensor.outdoor_temperature is the tag sensor.outdoor_temperature, live and in the copied history alike, with the friendly name Home Assistant shows as its description.
• Grafana. Through Grafana Labs' own Infinity data source and a ready dashboard — not through your old InfluxQL or Flux queries.

You gain

• No database to run. Nothing to upgrade, back up, or migrate again when the next major version lands.
• Long history without the disk. Full resolution for 14 days on Free, 1 year on Pro and 2 years on Business; after that, hourly minimum, maximum, average and count for 10 years on every plan, the free one included. See how long data is kept.
• A copy that is not in your house. A nightly backup to a geo-redundant vault whose offsite copy sits in a second Swedish region, with both recovery point objectives on where your data lives.
• Alerts. Email, push and chat when a value crosses a limit or a sensor goes quiet — see alerts.

You give up

• InfluxQL and Flux. Data comes out through the Tag Historian API, its charts, CSV, JSON or Parquet exports and Grafana — not through InfluxDB tooling.
• Text and attributes. Only numbers are stored, on and off as 1 and 0. An entity whose state is a word, like a climate entity at heat, has no number to keep.
• Money, past 5 tags. Free is €0 for 5 tags; more is a paid plan. A local InfluxDB costs only the machine.

1. Get an API key

Create an account and an API key first. The free plan is €0 and takes an email address — no card — and gives you 5 tags and 50,000 readings a day. Then create the key on the Settings page in Tag Historian Explorer — and the scope you give it is not a detail.

The key is shown once. Copy it straight into the TAGHISTORIAN_API_KEY variable below, and later Home Assistant's API token field — if you lose it, generate a new one rather than hunting for the old one.

2. Install the copy tool

taghistorian-influx-migrate is open source, in Python 3.9 or newer, with requests as its only dependency. Run it on any machine that can reach both your InfluxDB and the internet — your laptop is fine.

pip install "git+https://github.com/softi-dev/tag-historian-clients.git#subdirectory=influxdb-migration"

3. Look before you write

A dry run lists every tag the copy would write, how many readings each holds, its unit and friendly name, how many of the tags are new against how many your plan has room for, and how many days the copy takes. It writes nothing. For the InfluxDB app in Home Assistant, or any InfluxDB 1.x — the address, database and user are under Settings → Devices & services → InfluxDB → ⋮ → Reconfigure:

export TAGHISTORIAN_API_KEY='<your-write-key>'
export INFLUX_PASSWORD='<influxdb-password>'

taghistorian-influx-migrate --dry-run \
  --influx-url http://homeassistant.local:8086 \
  --database home_assistant --influx-username homeassistant \
  --entity 'sensor.*_temperature' --entity 'sensor.*_energy*'

For InfluxDB 2.x, a token that can read the bucket:

taghistorian-influx-migrate --dry-run \
  --influx-url http://192.168.1.20:8086 \
  --org home --bucket "Home Assistant" --influx-token '<read-token>' \
  --entity 'sensor.*'

Every tag costs one of your plan's, so choose: --entity takes the same shell-style patterns as Home Assistant's own include, and --exclude leaves things out. Without --entity the copy takes every Home Assistant entity it finds.

4. Copy the history, while Home Assistant still writes to InfluxDB

The same command without --dry-run. Each entity lands under the name live forwarding will give it, with its friendly name, and with its unit — which Home Assistant's InfluxDB integration writes as the measurement name, so the copy reads it from there (the dry run shows every unit before anything is written, and --no-unit-from-measurement turns that off).

The copy uses your plan's daily readings allowance — the same one live data uses — and stops each UTC day with 25% of it left, because Home Assistant drops a reading the allowance refuses rather than sending it later. So a big history takes days. When today's share is used, the command says so and exits; run it again after midnight UTC, by hand or from cron, or leave it running with --wait. It picks up exactly where it stopped, from a resume file it updates after every batch.

Tag Historian does take history outside the daily allowance, through its history import — but only readings inside your plan's full-resolution window, and only those older than a tag's first live reading. It is made for what Home Assistant's own recorder still holds. The years in InfluxDB reach far past that window, so the copy writes them the way live data is written.

That last column is 5,256,000 readings, and the copy gets less if live forwarding already sends a lot on the same account; the dry run does this sum with your own numbers, yesterday's live traffic included. Home Assistant only writes a sensor when it changes, so most real histories are far smaller than once a minute.

5. Catch up, then switch Home Assistant

1. When the copy says it has finished, run it once more with --catch-up. It moves the end of the range to now and copies what Home Assistant wrote to InfluxDB in the meantime.
2. Straight away, switch Home Assistant's live data to Tag Historian, one of the two ways below. Point only one of them at Tag Historian: both would send every reading twice.

• The Tag Historian integration, installed through HACS — the way we recommend from Home Assistant, because it sends each entity's unit, follows a renamed entity, and keeps readings through a restart. Pick the same entities the copy took, then delete the InfluxDB entry, or leave it writing to your own InfluxDB if you are keeping that too. The setup is the Home Assistant integration guide. Its tags are named after each entity id, as the copy's are — unless your InfluxDB integration adds tags of its own, from a tags: block for instance: the copy puts those in the tag names, as the InfluxDB integration does, and the Tag Historian integration does not, so take the second way instead.
• Home Assistant's InfluxDB integration, pointed at Tag Historian. On an InfluxDB 2.x connection that is Reconfigure; a 1.x connection cannot be reconfigured into a 2.x one, so delete it and add InfluxDB again as v2.x. Both are on the guide to the InfluxDB integration, with the values to enter.

Nothing is lost but the minutes between the last catch-up and the switch. The next section is why it is done in this order, and what to do if you have already switched.

6. Import the Grafana dashboard

grafana/home-assistant.json is the dashboard people build on InfluxDB, pointed at Tag Historian: an Entity dropdown, and one chart per entity, drawn in the tag's unit and labelled with its friendly name, with a small panel saying whether the line is stored readings or hourly averages. Every entity the copy brought across has its unit; one you add to Home Assistant afterwards gets its name from the integration but, on the integration's default settings, not its unit, which you set once on the tag's page in Explorer. It runs on Grafana Labs' Infinity data source, Grafana Cloud's free tier included. The Grafana guide sets that up — with a key of its own whose scope is Read, because a Grafana server is shared and nothing on a dashboard writes — and then it is Dashboards → New → Import.

Why the order matters

Tag Historian compares each reading with the newest one the tag already holds, and drops one that repeats it — to within the tag's deadband, unless an hour has passed since the last one it kept. That is how live data is stored, and it is right for live data. A history copied into a tag that live forwarding has already been writing is compared with last week's value instead, no hour ever passes, and every old reading that happens to equal it is dropped: for an on/off sensor, every reading in the state it is in now.

So the copy only ever writes readings newer than the newest a tag already holds. That is also what makes running it twice harmless — the write endpoint the copy uses, the one live data arrives by, stores what it is sent without looking for duplicates, and the copy never sends a reading the tag already has. If you switched Home Assistant over first, the dry run lists which tags already hold newer readings. --include-older copies everything anyway, at exactly the cost above: fine for a temperature that keeps moving, worst for an on/off sensor.

One exception: an entity whose tag was renamed in Tag Historian — by the Home Assistant integration following an entity rename, or by you in Explorer. InfluxDB holds that entity's older readings under its old id, and the copy looks tags up by the name it will write under. An old id is a former name in Tag Historian, not a tag, so the copy does not recognise it: the dry run counts it among the new tags, and copies its readings in full rather than only the newer ones — into the renamed tag, which is where Tag Historian stores anything sent under a former name. If live forwarding already brought the old id's readings across, leave it out with --exclude.

The limits, and where they come from

The copy does not take these from this page. It reads your own account's limits when it runs, refuses to start a selection your plan has no room for, and pauses rather than pushing past the day's allowance. When a request is refused for a reason that passes — a 429 or 503 — it waits as long as Tag Historian asks and sends the same batch again; when a request gets no answer at all, it asks Tag Historian whether the batch arrived before it sends anything twice.

What it does not copy

• Attributes, only the state — as live forwarding stores it.
• Entities whose state is a word. Live, Tag Historian turns each numeric attribute of one into a tag of its own; the copy leaves those out rather than spending tags you did not choose.
• Series that are not Home Assistant's — Telegraf's, say, in the same database. Telegraf writes to Tag Historian directly.
• InfluxDB 3. Not supported: it has no Flux, and its InfluxQL compatibility has never been tried with this copy.