Purge Recorder entities

Use this action to remove recorded data for specific entities, whole domains, or entities that match a pattern. This is handy when a few noisy entities take up most of your database, for example sensors that report every few seconds, and you want to clear their history without touching everything else.

You must provide at least one of the entities, domains, or entity globs options.

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 entities 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 entities.
6. Set the options you want to use.
7. Select Save.

Options in the UI

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_entities. A basic example looks like this:

action: recorder.purge_entities
data:
  entity_id: sensor.power_sensor_0

Options in YAML

Good to know

• You must provide at least one of entity_id, domains, or entity_globs. You can combine them to select exactly what to remove.
• To clean up the whole database based on age instead of specific entities, use the Purge Recorder database action.

More examples

Real scenarios where this action shows up in automations and scripts. Copy any example and adapt it to your setup.

Automation: remove data for a noisy sensor every night

If a sensor reports very frequently and fills up your database, you can remove its older data on a schedule. This example removes history for sensor.power_sensor_0 older than 5 days, every day at 04:15.

alias: "Purge noisy power sensor"
triggers:
  - trigger: time
    at: "04:15:00"
actions:
  - action: recorder.purge_entities
    data:
      keep_days: 5
      entity_id: sensor.power_sensor_0

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.

Related actions

These actions work well alongside this one:

• Purge Recorder database: Cleans up old data from the recorder database.

• Enable Recorder: Resumes recording events and state changes to the database.

• Disable Recorder: Stops recording events and state changes to the database.

• Get Recorder statistics: Retrieves long-term statistics for one or more entities.