History, Recorder, and data export

Why this matters

Once your devices and automations are running, you will almost certainly encounter two situations:

First: You want to know who left the balcony light on all night last Wednesday, or how much energy the air conditioner used this month. Data from three days ago is available, but data from three months ago is gone—even though last year’s energy use is still visible. This is intentional, and this chapter explains why.

Second: Home Assistant becomes unusually slow: a light takes three seconds to respond, and a restart takes ten minutes. An oversized database is a common cause. On a Raspberry Pi that uses a microSD card, sustained database writes can also shorten the card’s life.

By the end of this chapter, you will be able to:

• Choose between History and Activity (formerly Logbook) for a given question.
• Identify where Recorder stores data, how long it retains detailed history by default, and what affects database size.
• Use include and exclude to keep noisy entities out of Recorder.
• Export CSV data for analysis in Excel or Google Sheets.
• Purge an oversized database, respond safely to corruption, and choose a long-term storage option.

Chapter 9 covers general backup practices; this chapter focuses on how the database affects backups. See entity_id conventions in Chapter 4 for entity naming used in the filtering examples.

History and Activity answer different questions

The sidebar contains two similar entries: History and Activity. They answer different questions.

In everyday terms, History is the chart in a medical record; Activity is the nursing shift log. The former shows how values changed, while the latter shows who or what performed an action.

One practical difference is that Activity omits sensors with units by default. Temperature, humidity, and power sensors can update every few seconds and would overwhelm the event list. View those sensors in History instead.

Recorder: the source of all history

History and Activity are views; they do not store data themselves. The Recorder integration writes state changes to storage.

You usually do not install Recorder separately. History relies on Recorder, and both use the same database settings. A new installation enables them through configuration.yaml with default_config:.

Which file stores the data?

By default, Home Assistant uses SQLite. Its database is a single file in the configuration directory:

/config/home-assistant_v2.db

This single file contains the default Recorder database. Because it is stored beside configuration.yaml, a full backup normally includes it.

Default retention period

Recorder’s purge_keep_days setting defaults to 10 days. Detailed state changes older than that are deleted automatically.

Recorder also uses the following defaults:

How big will the database be?

Database size depends on both the number of entities and how often they change. Use these examples only as rough guidance:

The key question is how many records each entity generates per day. A light may change 6 times, while a power sensor that reports every second can create tens of thousands of rows. One such sensor can generate more data than all other entities combined.

Use these two views to check current storage use:

The later SQL integration section shows how to expose database size as a sensor on your dashboard.

Long-term statistics: why energy lasts longer than switch history

Detailed history and long-term statistics have different retention rules.

Detailed history defaults to 10 days, yet the Energy dashboard can still show last year’s consumption. Home Assistant stores these as two different types of data.

The states table records individual changes. Statistics compress those changes into fixed-interval summaries, producing only 24 hourly rows per day and making multi-year retention practical.

Which entities have long-term statistics?

Only entities with a supported state_class enter the statistics table. Chapter 17 explains each state class; here the focus is retention:

An energy meter with total_increasing retains long-term statistics, whereas a light’s nonnumeric on/off state has no state class and keeps only 10 days of detailed history by default.

This also explains why older History charts can look smoother and lose brief peaks. Within the detailed-history window, the chart uses full-resolution Recorder data; beyond it, the chart uses hourly long-term statistics. An hourly average will not exactly match any single reading. Home Assistant distinguishes the higher-resolution portion with a darker line.

Hands-on: Download history as CSV

Home Assistant can export History data to CSV without additional software.

1. Open History from the sidebar

   If History is not visible, select your name at the bottom of the sidebar, open your profile, and check whether the item is hidden. Alternatively, append /history to the Home Assistant URL and press Enter.

2. Select an area, device, or entity

   Use the selector at the top to choose an area, device, or entity. Selecting an area shows the charts for its entities, provided that you assigned areas as described in Chapter 3.

3. Set the time range

   Select Today, This week, or custom start and end dates. The selected range determines how many rows the CSV contains. Start with one day before requesting a large range.

4. Select Download data in the upper-right corner

   The English interface labels the button Download data; localized interfaces use the corresponding translation. Selecting it saves a CSV file directly to your browser’s download folder without opening a settings dialog.

   

5. Open it in a spreadsheet

   Open the file in Excel, Numbers, or Google Sheets. If non-Latin text is garbled, use the application’s import command and select UTF-8 instead of opening the file directly.

Export Activity events

Starting with Home Assistant 2026.8, Activity provides CSV download and a Clear and reset action. Choose the export that matches the data you need:

Tools → Statistics: Correct invalid values

Open Settings → Tools. Its tabs include YAML, States, Actions, Templates, Events, Statistics, and Assist.

The Statistics page has two essential functions.

1. Identify entities with statistics problems

The page lists entities with long-term statistics. Affected entries have a Fix issue link that explains the detected problem. Common cases include:

2. Correct a value for a specific hour

This tool can correct an isolated, invalid reading. For example, a meter might jump to 999999 kWh and flatten the rest of the month’s Energy chart. See Chapter 17 for energy statistics.

Home Assistant’s documentation instructs you to select the icon beside the entity, locate the data point with the date and time fields, and edit its value.

1. Find the affected time on the Energy or History chart

   Point to the implausible bar and note its date and hour.

2. Go to Settings → Tools → Statistics and find the entity

   Use the search box to find the entity by name.

3. Open the adjustment tool and locate the record by date and time

   It displays the value recorded for that hour.

4. Enter a reasonable value, save it, and review the chart

   You may need to refresh the page before the chart reflects the change.

Use include and exclude to streamline Recorder data

An oversized database is usually caused by high-frequency entities you never review, not by ordinary lights. Start by telling Recorder not to store unnecessary data.

Write these settings in configuration.yaml, run a configuration check, and restart Home Assistant for them to take effect.

Method A: Exclude selected data (recommended for beginners)

Record everything by default, then exclude only known noisy data. This approach reduces the chance of omitting important history.

recorder:
  purge_keep_days: 10
  exclude:
    domains:
      - automation
      - update
    entity_globs:
      - sensor.sun*
      - weather.*
    entities:
      - sensor.date
      - sensor.last_boot
    event_types:
      - my_custom_event

Method B: Include selected data (for tightly controlled databases)

This reverses the default: Recorder stores only the data you name. It offers the most control, but can easily omit history you later need.

recorder:
  include:
    domains:
      - sensor
      - switch
      - media_player
  exclude:
    entities:
      - sensor.last_boot
      - sensor.date
    entity_globs:
      - sensor.weather_*

You can combine the two: use include for a broad set, then exclude for exceptions. The Home Assistant documentation gives the complete precedence rules. As a general guide, more specific rules take priority: explicit entities outrank globs, and globs outrank domains.

Four filter types

Common sources of excessive writes

Purge stored data safely

Filtering reduces future growth but does not shrink existing data. Recorder provides these actions (formerly called services):

The three recorder.purge parameters

After adding exclusion rules and restarting Home Assistant, this combination removes old rows that now match the filters and repacks the database:

action: recorder.purge
data:
  keep_days: 7
  repack: true
  apply_filter: true

Open Settings → Tools → Actions, select recorder.purge, switch to YAML mode, paste the example, and run it. In older versions, this area was named Developer tools and appeared in the sidebar.

Purge only one noisy entity

If one power sensor is causing the growth, do not purge unrelated history. recorder.purge_entities accepts entity_id, domains, or entity_globs. Its keep_days default is 0, which deletes all matching data.

The Home Assistant documentation provides a useful automation example that retains only the most recent 5 days of detailed data for this power sensor:

alias: Clear old data from noisy power sensors every day
triggers:
  - trigger: time
    at: "04:15:00"
actions:
  - action: recorder.purge_entities
    data:
      keep_days: 5
      entity_id: sensor.power_sensor_0
mode: single

This preserves the recent detailed curve without allowing it to grow indefinitely. Long-term statistics are unaffected, so annual trends remain available if the sensor has a supported state class.

The default auto_purge runs at 04:12 each morning, so manual purging is normally unnecessary. Use it after changing filters when you need them applied to old data, or when urgent database cleanup is required.

Database backups and corruption recovery

Full backups include the database

Because home-assistant_v2.db is in the configuration folder, a full backup normally includes it. A large database therefore makes every full backup larger. A 2 GB database included in three retained backups can consume about 6 GB before accounting for other backup content or compression.

To reclaim storage, purge unneeded database rows, filter unnecessary Recorder data, and reduce purge_keep_days if appropriate. Also set backup-retention limits and keep an independent copy outside the Home Assistant host.

Use this order: configure exclusions → restart Home Assistant → run recorder.purge with repack → create a new backup.

Changing databases does not migrate existing history

Symptoms of database corruption and how to respond

Common causes of SQLite corruption include a power failure during a write and failing storage. Home Assistant may still open, while History and Activity are empty and the logs contain database errors.

1. Confirm the diagnosis

   Open Settings → System → Logs and look for errors containing sqlite or database.

2. Understand Home Assistant’s automatic recovery

   If SQLite is irreparably damaged, Home Assistant moves the damaged database aside and creates a new one. Your settings, automations, and devices remain intact; the unavailable data is history.

3. Make sure there is enough disk space

   Home Assistant recommends free space of about 2.5 times the database size when recovering a damaged SQLite database. Recovery may fail without enough space.

4. Address the history loss and its root cause

   Follow the linked SQLite recovery guidance if the history is important. Otherwise, preserve the damaged .db file for later analysis, allow Home Assistant to start a new database, and address the cause: failing storage or unsafe power removal.

Advanced 1: Switch from SQLite to MariaDB

SQLite is a simple, zero-configuration, single-file database. With many entities and frequent writes, a database server may offer better performance.

Home Assistant documents the following minimum supported versions:

On Home Assistant OS, install the MariaDB App from the Home Assistant repository under Settings → Apps. Home Assistant 2026.2 renamed Add-ons to Apps, so older instructions may say “Add-on store.” Apps are available only on Home Assistant OS. After installation, add this to configuration.yaml:

recorder:
  db_url: mysql://homeassistant:YOUR_PASSWORD@core-mariadb/homeassistant?charset=utf8mb4
  purge_keep_days: 14

core-mariadb is the App’s hostname on the internal network. The username, password, and database name must match the App configuration. For a database on another host, use the documented URL format:

mysql://user:password@SERVER_IP/DB_NAME?charset=utf8mb4
postgresql://user:password@SERVER_IP/DB_NAME

Advanced 2: InfluxDB and Grafana for long-term data

This architecture separates control, time-series storage, and visualization:

The official InfluxDB integration writes an additional copy of selected state data to InfluxDB. Local Recorder continues to run independently. You can therefore keep 7 days of detailed Recorder history while applying a separate 3-year retention policy in InfluxDB.

Key configuration points:

• InfluxDB 1.x uses a host URL, username, password, and database name. Authentication is optional and disabled by default.
• InfluxDB 2.x and 3.x use an organization, bucket, and access token. Authentication is required, and api_version: 2 selects the newer API. The integration documentation covers 1.x, 2.x, and 3.x.
• For every version, configure filters. The integration supports include and exclude rules for domains, entities, and entity_globs. Sending every entity to InfluxDB merely moves uncontrolled growth to another database.

InfluxDB and Grafana are available as community-maintained Apps from the hassio-addons Home Assistant Community Apps repository; they are not official Home Assistant Apps. Add that repository before installation, as described in Chapter 20 and Appendix A. Apps are available only on Home Assistant OS; Container and Core installations require separate InfluxDB and Grafana deployments.

Advanced 3: Turn a SQL query into a sensor

The SQL integration turns the result of a SQL query into an entity that you can display on a dashboard or use to trigger an automation. You can add it through the UI configuration flow or YAML.

A classic use is to expose database size as a sensor and monitor it directly on a dashboard.

1. Settings → Devices & services → Add integration

   Select the button in the lower-right corner and search for SQL.

2. Leave the database URL blank

   db_url is optional. Leave it blank to query the database currently used by Recorder.

3. Paste the query statement

   For SQLite, Home Assistant provides this example query:

   SELECT ROUND(page_count * page_size / 1024 / 1024, 1) as size
   FROM pragma_page_count(), pragma_page_size();

4. Enter size as the result column

   Enter size, matching as size in the query. The query must return only one row.

5. Set the name and unit

   Name the entity “Database size” and set its unit to MiB. You can also set the device class to Data size so that the interface converts units automatically.

Add the resulting sensor to a dashboard as described in Chapter 6. You can also notify yourself when it exceeds a chosen threshold; see Chapter 7.

alias: Notify me if the database is too big
triggers:
  - trigger: numeric_state
    entity_id: sensor.database_size
    above: 2000
    for: "01:00:00"
conditions: []
actions:
  - action: notify.persistent_notification
    data:
      title: Database warning
      message: The database has exceeded 2000 MiB (approximately 2 GB), it's time to find out who is spamming it.
mode: single

notify.persistent_notification creates a persistent notification in the Home Assistant interface and requires no prior setup, making it suitable for testing. To notify a phone, use the action configured in Chapter 7. for: "01:00:00" requires the value to remain above the threshold for one hour, reducing alerts caused by brief fluctuations.

Common problems

1. Home Assistant responds very slowly

   Check Settings → System → Storage for free space, then view the estimated database size in Repairs. If the database is several GB, identify high-frequency sources, add appropriate exclude rules, restart, then run recorder.purge with repack: true and apply_filter: true. Confirm adequate free space before repacking.

2. The memory card has failed and the system will not start

   Recorder writes at each commit_interval, and sustained database growth places a heavy write load on consumer microSD cards. There is no universal lifespan figure. Reduce unnecessary writes by increasing commit_interval cautiously and excluding noisy entities; for long-term reliability, migrate the installation to suitable SSD or high-endurance storage.

3. All history disappeared after a restart

   Check the logs. A damaged database may have been moved aside while Home Assistant created a new one; database errors will identify this case. Alternatively, you may have switched from SQLite to MariaDB. Existing-history migration is not officially supported, so a new database begins empty by design.

4. An entity is completely absent from History

   Check whether an exclude rule removed it or an include rule omitted it. Then confirm that the entity is enabled as described in Chapter 11. If it appears in History but not Activity, that can be normal because Activity omits sensors with units by default.

5. Cleanup finished, but free disk space did not increase

   This is normal. Purging rows does not immediately return space to the operating system. repack rewrites the database to reclaim that space. The default auto_repack runs every second Sunday; if space is urgently needed and sufficient working space is available, run a purge with repack: true.

6. An extreme value flattened the Energy chart

   Open Settings → Tools → Statistics, locate the entity and timestamp, and correct the invalid value. Make a backup first and follow the detailed procedure in this chapter’s Tools → Statistics section.

7. The downloaded CSV contains garbled text

   Do not open the file by double-clicking it. In Excel, use Data → From Text/CSV and select UTF-8. In Google Sheets, use File → Import; it usually detects the encoding automatically.

8. A Recorder action is missing or does not run

   Use Settings → Tools → Actions, not Developer tools in the sidebar; that location was removed in 2026.2. Recorder actions also require Administrator privileges. Switch from a standard account to an Administrator account and try again.

FAQ