Long-term statistics

By default, Home Assistant saves every state change of your entities in its database, and keeps it for 10 days. For many sensors, it also saves statistics, of two kinds: short-term statistics every 5 minutes, and long-term statistics every hour. Short-term statistics are deleted together with the state history. Long-term statistics are never deleted automatically. With them, you can look back at your energy use or the temperature in your home over months and years.

You don’t have to set anything up. Home Assistant creates both kinds automatically for the sensors that support them. On this page, “statistics” means both kinds. Where only one kind applies, the page says which.

Both kinds are different from the Statistics integration. That integration is a helper that creates a new sensor, for example, the average of another sensor over the last hour.

Which sensors have statistics

Home Assistant keeps statistics for a sensor when all of the following are true:

• The sensor has a state class. The integration that provides the sensor usually sets the state class.
• The state of the sensor is a number.
• The sensor is recorded. If you exclude an entity from the recorder, Home Assistant doesn’t keep statistics for it.

Only sensor entities get statistics this way. Other entities, such as lights or switches, don’t.

To find out whether a sensor has a state class, go to Settings > Tools > States, and look for the state_class attribute of the sensor. If a sensor that you create yourself, such as a template sensor, has no state class, you can set one in its options.

About short-term and long-term statistics

The two kinds differ in how often Home Assistant saves them, and how long it keeps them:

• Short-term statistics
  • Saved every 5 minutes.
  • Kept as long as the state history, by default 10 days. You can change this with the purge_keep_days option of the recorder.
• Long-term statistics
  • Saved every hour, calculated from the short-term statistics.
  • Never deleted automatically. You can delete them yourself in the Statistics tab.

What the statistics contain

Short-term and long-term statistics contain the same values, for a period of 5 minutes or of 1 hour. Which values Home Assistant saves depends on the state class:

• Measurement
  • The average, the lowest, and the highest value in each period.
  • The average is weighted by time: a value that stays the same for 4 minutes counts four times as much as a value that lasts 1 minute. So a sensor that updates unevenly still gets a correct average.
• Measurement angle
  • The average angle in each period, also weighted by time. Home Assistant calculates the average so that, for example, 350° and 10° for the same amount of time give 0°, not 180°.
• Total and Total increasing
  • The sum: how much the value has changed since Home Assistant started keeping statistics for the sensor. The first value it sees is the starting point.
  • The last value in each period.

For Total increasing, what happens when the value drops depends on how much it drops:

• A drop of more than 10% counts as a reset, for example, when a meter starts again from zero.
  • The sum continues from where it was, so the reset doesn’t count as a negative amount.
• A drop of 10% or less doesn’t count as a reset.
  • The sum goes down by that amount.
  • Home Assistant can log a warning that the state of the sensor isn’t strictly increasing.
• A negative value is skipped, and Home Assistant logs a warning.

For Total, the sum can go up and down. A reset works differently:

• The integration signals a reset with the last_reset attribute of the sensor, which holds the time of the last reset.
  • When last_reset changes, Home Assistant starts a new cycle. The sum keeps what was counted so far, and the new value counts from zero.
• If the sensor has no last_reset attribute, Home Assistant doesn’t detect resets. The sum follows the value up and down.

Where statistics are used

Home Assistant uses statistics in these places:

• The Energy dashboard uses the long-term statistics of your energy, gas, and water sensors. For power graphs of short periods, about a week or less, it uses the short-term statistics.
• The Statistics graph card shows statistics for the period that you choose. With 5 minutes, it shows the short-term statistics. With Hour or longer, it shows the long-term statistics.
• The Statistic card shows one value, such as the average temperature today. It combines both kinds, so the period can start and end at any 5-minute mark, not only on the full hour.
• The History graph card and the History panel show the state history. For older periods, when the state history has already been deleted, they show the long-term statistics instead.

About long-term statistics from integrations

Some integrationsIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] add long-term statistics directly, without a sensor, for example, the hourly energy use that they get from your energy provider. These statistics have an ID with a colon instead of a dot. The part before the colon is the integration, for example, opower: for the Opower integration. You can use them in the Energy dashboard and in statistics cards, like the statistics of a sensor. To find them, go to Settings > Tools > Statistics.

When the unit or the state class changes

Both kinds of statistics only work if the values stay comparable over time. Home Assistant checks this every 5 minutes, when it saves the short-term statistics. The long-term statistics are calculated from them, so if the short-term statistics stop, the long-term statistics stop too:

• If the unit of a sensor changes to another unit of the same kind, for example, from W to kW, the statistics continue.
  • Home Assistant keeps saving the statistics in the original unit, W in this example, and converts the new values to it.
  • The Statistics graph card shows the statistics in the current unit of the sensor, kW in this example.
• If the unit changes to a unit that can’t be converted, for example, from kWh to m³, Home Assistant stops the statistics for the sensor until you fix it.
• If the sensor no longer has a state class, Home Assistant stops the statistics for it.
• If the state class changes between Measurement and Measurement angle, Home Assistant stops the statistics for the sensor, because it calculates the average differently. The statistics continue when the state class changes back, or after you delete the old statistics.

In these cases, an issue appears in Settings > Tools > Statistics, and often also under Settings > System > Repairs. For how to fix it, refer to Fixing a statistics issue.

Good to know

• If you delete a sensor, its long-term statistics stay. The Statistics tab shows the issue “There is no state available for this entity.”, and you can delete the statistics there.
• If you change the entity ID of a sensor, its statistics move to the new entity ID. Changing the name of a sensor doesn’t affect its statistics.
• If you exclude an entity from the recorder later, its existing long-term statistics stay. You can delete them in the Statistics tab.
• To correct a wrong value, for example, a spike in your energy use, refer to Adjusting a statistic.