2026.6.3
Home ▸ Actions

Purge Recorder database

Use this action to clean up old data from the recorder database. It removes events and state changes older than the number of days you keep, which helps control how large the database becomes. This is handy when you want to free up space or keep growth in check, for example by running a regular cleanup.

Only users with administrator rights can run this action.

Using this action from the user interface

If you prefer building automations and scripts visually, Home Assistant walks you through this action step by step. You pick what to target, tweak a few options, and save. No YAML knowledge required.

To purge the database from an automation or a script:

  1. Go to Settings > Automations & scenes.
  2. Open an existing automation or script, or select Create automation > Create new automation.
  3. If you’re setting up a new automation, add a trigger in the When section. Scripts don’t need a trigger. They run when something else calls them.
  4. In the Then do section, select Add action.
  5. From the list of actions, search for and select Purge Recorder database.
  6. Set the options you want to use.
  7. Select Save.

Options in the UI

Days to keep (Optional)

The number of days of history to keep, counting back from today. For example, a value of 7 keeps the last week and removes everything older. If omitted, the recorder uses the number of days set in its configuration.
Repack (Optional)

Rewrites the entire database to try to free up disk space. This is a heavy operation that can cause slowdowns and temporarily use more disk space while it runs.
Apply filter (Optional)

Also applies the entity and event filters from your recorder configuration, on top of the time-based cleanup. Useful for removing data that was recorded by mistake.

Using this action in YAML

If you work directly in YAML, or you want to know exactly what Home Assistant does under the hood, this section has the technical reference. It lists the field names you use in YAML, their types, and which ones are required.

In YAML, refer to this action as recorder.purge. A basic example looks like this:

ActionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called *sequence*. [Learn more] 
action: recorder.purge
data:
  keep_days: 7

Options in YAML

keep_days integer

The number of days of history to keep, counting back from today. For example, a value of 7 keeps the last week and removes everything older. If omitted, the recorder uses the number of days set in its configuration.

repack boolean

Rewrites the entire database to try to free up disk space. This is a heavy operation that can cause slowdowns and temporarily use more disk space while it runs.

apply_filter boolean

Also applies the entity and event filters from your recorder configuration, on top of the time-based cleanup. Useful for removing data that was recorded by mistake.

Good to know

  • Purging does not immediately reduce disk usage, but it significantly slows down further growth. To reclaim disk space, use the Repack option, keeping in mind it is a heavy operation.
  • To remove data for specific entities, domains, or patterns instead of a time-based cleanup, use the Purge Recorder entities action.

Still stuck?

The Home Assistant community is quick to help: join Discord for real-time chat, post on the community forum with the action you’re calling and what you expected to happen, or share on our subreddit /r/homeassistant.

Tip

AI assistants like ChatGPT or Claude can also explain actions or suggest the right one when you describe what you want in plain language.

Related actions

These actions work well alongside this one: