Add Tag Historian to Home Assistant with a picker, not YAML

What this adds

• No YAML, no restart. Entity selection is a picker, and changing it later is a picker again — one restart at install, and never again for a config change.
• The picker is a short list. A normal Home Assistant install has several hundred entities and almost none of them are worth a tag. What you get is the things whose job is to report something — sensors, binary sensors, numbers, counters — with the best ones already ticked. The list is decided by what each entity is, not by what it happens to read at that moment, so a flat battery never removes anything from it. Everything else is one toggle away, not gone.
• The quota is visible while you choose. Tag Historian charges by the number of tags, not by how much data they hold, so which entities you send is the decision that matters. This shows you the budget as you spend it, and refuses to let you sail past it without saying so.
• History survives a rename. Rename an entity in Home Assistant, or replace a meter and give the new one the old one's id, and the tag follows it with its history intact — nothing is lost, nothing starts over, and it does not cost a second tag unless you ask for one. See when you rename an entity.
• It can tell you why data stopped arriving. The built-in integration cannot: it has one failure mode, it never reads the Retry-After header, and it has no notion of the API's “some of that batch was refused” answer. This one turns each of those into a Repairs card that says which problem it is and what to do — a revoked key, entities beyond your plan's tag count, the daily reading allowance being spent, or Tag Historian simply being busy. The last two are different problems and are never described as the same one.
• It brings the history you already have. The recorder on the box holds days of readings from before you installed anything — on an SD card, more often than not, the part most likely to fail. One action copies them into Tag Historian with their original timestamps, outside your daily reading allowance. See import the history you already have.
• A restart or an outage does not cost you your readings. Readings it could not deliver are saved when Home Assistant stops and sent when it starts again, and readings it had to let go of during an outage are read back from the recorder while the recorder still has them.

1. Install through HACS

The button opens the integration in HACS on your own Home Assistant, through My Home Assistant, which asks for your Home Assistant's address the first time. HACS asks whether to add the repository: press Add, then Download, and restart Home Assistant. Without the button:

1. HACS → the three-dot menu (top right) → Custom repositories.
2. Repository: https://github.com/softi-dev/tag-historian-clients. Category: Integration.
3. Install Tag Historian, then restart Home Assistant.

Prefer not to add a custom repository? Copy custom_components/tag_historian/ from the same repository into your Home Assistant config/custom_components/ directory and restart — HACS just automates that copy and keeps it updated for you.

2. 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 Connect screen when you add the integration — if you lose it, generate a new one rather than hunting for the old one.

3. Set up the integration

The button works once the integration is installed and Home Assistant has restarted. By hand it is Settings → Devices & services → Add integration → Tag Historian. Three screens, and the last one recomputes from what you actually picked:

Connect

Host (leave the default alone unless you self-host) and your API key. The key is checked against your account before anything is saved, so a typo — or a key with the wrong scope — is caught here rather than a week later.

Choose

The entities whose job is to report something — sensors, binary sensors, numbers, counters — with the best candidates already ticked and spread across your devices, cut off at the number of tags your plan has left. Things you operate rather than measure — lights, switches, locks, automations, scripts, update entities, the sun — stay out of the list until you tick Show every entity, which puts every entity in the install back into it, unfiltered. There is also a minimum interval, which is how you stop a chatty sensor spending your daily reading allowance, and a switch, Rename tags when entities are renamed, off until you turn it on — what it does is further down.

A sensor with no device class and no state class is listed but left unticked — Home Assistant knows nothing about those either way, and a few of them report a word instead of a number. See what one entity costs for what happens if you tick one of those anyway.

Review

The same sums, recomputed from what you actually ticked. If everything fits, that is all the screen says. If your selection needs more tags than you have left, it says so instead and offers to trim it back for you — removing the lowest-ranked entities that need a new tag, and never one whose tag already exists, because that one was costing you nothing. If your account has no free tags at all and everything you picked would need one, setup stops and says so rather than finishing with an empty selection.

Change any of it later: Settings → Devices & services → Tag Historian → Configure → Change what you keep history for.

4. Import the history you already have

From version 2026.11.0 of the integration. Configure → Import the history Home Assistant has already recorded, pick the entities and how far back, and submit — or call the action from a script or an automation:

action: tag_historian.import_history
data:
  entity_id:          # optional: default is every entity you keep history for
    - sensor.house_power
  days: 30            # optional: default is as far back as your plan's window

It reads what Home Assistant's recorder holds for those entities and sends it with the original timestamps, through the same rules as the live readings: the same numbers and on/off words, unavailable left as a gap, the same minimum interval, timestamps to the second. It runs in the background — the sensor.tag_historian_history_import sensor shows how far it is, a notification says when it is done and what it did, and a restart carries it on where it stopped.

What Tag Historian holds an import to:

• An import allowance instead of the daily one. Imported readings do not count against your daily reading allowance. Each account may import, across all its imports together, its plan's daily readings times its full-resolution window in days — what the plan could have stored in that window. The import screen shows what is left; a larger plan raises it. When it is used up the import stops and says so, and live readings carry on unaffected.
• The plan's full-resolution window. Readings older than it are skipped, so the import starts there.
• History only. Readings older than the moment the import started, older than the first reading of the entity Tag Historian received live, and older than the start of the first import of that entity — under its current id or any id it had before a rename Tag Historian followed. Everything after that is live data, which the integration sends itself — including readings still waiting to be sent, so nothing arrives twice. Importing the same history again works; feeding an entity fresh readings through imports does not, renamed or not.
• The tag limit and the storage cap, as for live data. An imported entity uses a tag like a forwarded one, so only entities you keep history for can be imported.

Running an import twice stores nothing twice: Tag Historian skips a reading it already has for that tag at that timestamp — under its current name or one it had before a rename or a merge — and a skipped reading costs no allowance. Imported readings go through the tag's deadband like live ones, and raise no alerts — it is last month, not now.

What one entity costs

One selected entity is exactly one Tag Historian tag — no more, no asterisks. The integration sends at most a single numeric reading per state change and never a second tag for the same entity, so the count on the Review screen is the count you will be billed for.

Only the entity's own state is sent as a reading, never its attributes. Two attributes go along to describe it: the friendly name becomes the tag's description and the unit of measurement its unit, which is what Tag Historian Explorer labels charts with — rename the entity in Home Assistant and the description follows with its next reading. (From version 2026.10.0 of the integration; HACS offers the update.) A reading is therefore a number, or one of a small set of words that are a number in disguise: on/off for a light, a switch, a fan, an automation, a helper or a binary sensor, open/closed for a cover, above_horizon/below_horizon for the sun. Those become 1 and 0.

Everything else stores nothing at all, and the ones that catch people out are worth naming:

The last three are the reason the rule is about the domain rather than the word. A lock, a person and a plain sensor can each report a word this integration recognises and several it does not, so translating only the recognised ones would produce a chart that jumps to 1 for one state and shows nothing for the rest — a series that looks like data and is not. Storing nothing at all is the honest answer, and each of those state changes moves the readings dropped counter, which also names the offending entity in its attributes. If you want a number out of one of these, make a template sensor that exposes it as its own entity, and select that instead.

An entity that is unavailable or unknown when you open the picker is still listed, and one you have already selected stays selected — its state right now decides whether there is a reading to send, never whether you are allowed to choose it. unknown and unavailable are never sent, and never counted as dropped either: they are Home Assistant saying it has nothing to report. A gap in the chart means exactly that — Tag Historian never stores an invented zero.

When you rename an entity

A tag is named after its entity's id: sensor.energy_meter is stored as the tag sensor.energy_meter. Rename the entity in Home Assistant and this integration follows it: the selection is updated to the new id and readings keep arriving. Before version 2026.11.0 they stopped without a word, because the integration was still listening for an id that no longer existed.

The history follows as well, in one of two ways:

• With Rename tags when entities are renamed switched on, the integration asks Tag Historian to rename the tag to the new id straight away. Nothing is copied or moved: the readings from before stay where they are stored and read under the new name, and it is still one tag. If Tag Historian cannot be reached, the integration asks again later, and the readings go on into the tag under its old name meanwhile.
• With it off, the readings go on into the tag the entity already has, so nothing is lost and no second tag is started, and a Repairs card asks what you want: rename the tag and keep its history, or start a new tag under the new id and leave the history where it is, under the old name — which takes one more tag on your plan.

If the new id already has a tag of its own — you replaced a meter and gave the new one the old one's id — the bit stored under the renamed entity's old id is merged into it, straight away or when you say so on the card, the same two ways as above. Until then the readings go on into the old id's tag, so nothing is lost while it waits, and from then on into the merged one. The two then read as one history under that name, and the merged-in one stops counting against your plan. Where both have readings in the same hour, that hour's figures are worked out from both. Readings are never adjusted: a replacement meter that started from zero still shows the drop where the two histories meet.

Tag Historian keeps the old id as a former name of the tag. Anything still sent under it — a script, or the built-in influxdb integration — is stored in the renamed tag, and a chart or a query that asks for the old name gets the renamed tag. Both are reversible in Tag Historian Explorer, under Tags: a rename by renaming the tag back, a merge with Separate next to the name under Former names.

Sensors it adds

The last one is there on purpose: nothing is dropped silently, so if data is missing there is always a counter that moved. Its state adds up every way a reading can fail to become history:

entities_storing_nothing names the entities behind that last one, so a chart that stays empty says why. dropped_rate_limited is on the attributes too but is deliberately not in the total — those are the readings your minimum interval skipped, which is what you asked it to do. Two more attributes are not losses but what happened next: backfilled_from_recorder, readings read back from the recorder to fill a gap, and restored_after_restart, readings saved at the last stop and sent after it.

The counters keep their values across a reload, so fixing a Repairs card does not erase the evidence of what it was telling you about. A Home Assistant restart clears them — they are held in memory — while the readings they describe are saved and sent, and anything that could not be is written to the log as well as counted.

When something goes wrong

Everything below shows up in Settings → Repairs.

What this is not

• It does not read back into Home Assistant. There is no query API and no Flux here either — data comes out through the Tag Historian API, its charts, and exports to CSV, JSON or Parquet.
• It is not a replacement for the recorder. Home Assistant still keeps its own database and still draws its own charts from it. This is a copy that outlives the box.
• Strings and attributes are not stored. Only numbers, and the booleans this integration converts to 1 and 0.

No HACS?

Home Assistant's own influxdb integration talks to Tag Historian too, with nothing to install: a dialog for the connection, a short block of YAML for the entity filter, and a restart or a reload whenever that filter changes. Tag Historian cannot read a unit from what it sends, it does not follow a renamed entity, and it brings no history from before it was set up. That path, and the four settings that decide whether it works, are on the built-in integration guide.