Get Recorder statistics

Use this action to retrieve long-term statistics, such as the mean, minimum, maximum, or sum, for one or more entities over a time period. This is handy when an automation or script needs historical values, for example to compare this week’s energy use with last week’s.

This action returns its result in a response variable, which you can use in later steps of the same automation or script.

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 get statistics 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 Get Recorder statistics.
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.get_statistics. Store the result in a response variable so you can use it in later steps:

action: recorder.get_statistics
data:
  statistic_ids:
    - sensor.energy_meter
    - sensor.water_usage
  start_time: "2025-06-10 00:00:00"
  end_time: "2025-06-11 23:00:00"
  period: hour
  types:
    - sum
    - mean
  units:
    energy: kWh
    volume: L
response_variable: consumption_stats

Options in YAML

Response data

The action returns the statistics keyed by each statistic ID you requested. Each one holds a list of periods. Every period always includes a start and end, plus the value types you asked for:

• start: The start of the period.
• end: The end of the period.
• change: The change in value during the period.
• last_reset: The time the value was last reset, for metered values.
• max: The highest value during the period.
• mean: The average value during the period.
• min: The lowest value during the period.
• state: The recorded state at the period.
• sum: The running total at the end of the period.

A shortened example of the response looks like this:

statistics:
  sensor.energy_meter:
    - start: "2025-06-10T00:00:00+00:00"
      end: "2025-06-10T01:00:00+00:00"
      sum: 1234.5
      mean: 0.42
    - start: "2025-06-10T01:00:00+00:00"
      end: "2025-06-10T02:00:00+00:00"
      sum: 1236.1
      mean: 0.39

Good to know

• Only entities that store Long-term statisticsHome Assistant saves long-term statistics for a sensor if the entity has a state_class of measurement, total, or total_increasing. For short-term statistics, a snapshot is taken every 5 minutes. For long-term statistics, an hourly aggregate is stored of the short-term statistics. Short-term statistics are automatically purged after a predefined period (default is 10 days). Long-term statistics are never purged. [Learn more] return data. If an entity has no statistics, it is not included in the response.
• The value types you set in Types decide which fields each period contains, on top of the start and end that are always present.

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.

• Purge Recorder entities: Removes recorded data for specific entities, domains, or patterns.

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

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