2026.4.4
Home ▸ Integrations

ecobee

The ecobee integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] lets you control and view sensor data from ecobee thermostats.


Prerequisites

  • Username and password for ecobee.com.
    • You will need it when adding the integration to set up a connection between the integration and Home Assistant.
  • Have the devices connected to your ecobee.com account.
    • You can add devices either before or after you configure the service in Home Assistant, but having them connected to your ecobee.com account ahead of time is recommended to confirm that they are picked up by the service correctly.

Note

Since version 2026.3, it is no longer required to get a developer API key to use this integration. Existing API keys will continue to function. If you revoke your existing key in the ecobee portal, the integration will fail, and you will need to remove the service in Home Assistant and set it up again.

Configuration

To add the ecobee hub to your Home Assistant instance, use this My button:

ecobee can be auto-discovered by Home Assistant. If an instance was found, it will be shown as Discovered. You can then set it up right away.

Manual configuration steps

If it wasn’t discovered automatically, don’t worry! You can set up a manual integration entry:

API key

If you have a developer API key, use this field and ignore the others. If you are logging in without an API key, leave this field blank and use username and password.

username

The email address you use to sign in to ecobee.com.

password

The password for the above account.

Notifications

The ecobee notify platform allows you to send notifications to an ecobee thermostat. For each thermostat found, a notify entity will be added.

Example action:

action: notify.send_message
data:
  message: "Hello, this is your thermostat."
  entity_id: notify.ecobee

To use notifications, please see the getting started with automation page.

Thermostat

Concepts

The ecobee thermostat supports the following key concepts.

The target temperature is the temperature that the device attempts to achieve. The target temperature is either determined by the currently active climate or it may be overridden by a hold. When the thermostat is not in auto mode, there is a single target temperature. When the thermostat is in auto HVAC mode, there is a pair of target temperatures: the lower target temperature determines the lowest desired temperature, while the higher target temperature determines the highest desired temperature (the thermostat will switch between heating and cooling to keep the temperature within these limits).

A climate is a predefined or user-defined set of presets that the thermostat aims to achieve. The ecobee thermostat provides three predefined climates: Home, Away, and Sleep. Ecobee refers to these as comfort settings. The user can define additional climates.

A preset is an override of the target temperature defined in the currently active climate. The temperature targeted in the preset mode may be explicitly set (temperature preset), it may be derived from a reference climate (home, away, sleep, etc.), or it may be derived from a vacation defined by the thermostat. All holds are temporary. Temperature and climate holds expire when the thermostat transitions to the next climate defined in its program. A vacation hold starts at the beginning of the defined vacation period and expires when the vacation period ends.

When in away preset, the target temperature is permanently overridden by the target temperature defined for the away climate. The away preset is a simple way to emulate a vacation mode.

The HVAC mode of the device is the currently active operational modes that the ecobee thermostat provides: heat, cool, auto, and off.

The target humidity is the humidity set point of the thermostat when a humidifier is connected and in manual control or “On” mode.

On a thermostat configured with auxiliary heat, an aux_heat_only switch will be present. When this switch is turned on, the ecobee thermostat HVAC mode will be changed to “Aux”. However, Home Assistant will reflect that the thermostat is in “heat” mode. Turning off the aux_heat_only switch will change the thermostat back to the last active HVAC mode (heat, auto, etc).

Attributes

The ecobee climate entity has some extra attributes to represent the state of the thermostat.

Name Description
fan If the fan is currently on or off: on / off.
climate_mode This is the climate mode that is active, or would be active if no override is active.
equipment_running This is a comma-separated list of equipment that is currently running.
fan_min_on_time The minimum amount of time (in minutes) that the fan will run per hour. This is determined by the minimum fan runtime setting which can be changed in the ecobee app or on the thermostat itself.

Ventilator

Concepts

The ecobee thermostat supports the addition of an accessory. If you have an air exchanger (ventilator, HRV, or ERV), you can control it via the minimum time home and minimum time away numbers.

Switch

The ventilator 20 min switch is behaving like the switch in the physical ecobee device. When switched on, the ventilator turns on for 20 min. When turned off, it stops the ventilator.

Note: this does not interact with the ventilator min time

Number

Name Description
ventilator_min_on_time_home The minimum amount of time (in minutes) that the ventilator will run per hour, when you are home. This is determined by the minimum ventilator runtime setting which can be changed in the ecobee app or on the thermostat itself.
ventilator_min_on_time_away The minimum amount of time (in minutes) that the ventilator will run per hour, when you are away. This is determined by the minimum ventilator runtime setting which can be changed in the ecobee app or on the thermostat itself.

Auxiliary Heat

Concepts

When an HVAC system is equipped with a heat pump, a form of auxiliary heat is usually included. This may also be referred to as ‘Emergency Heat’. You can control whether the thermostat requests only auxiliary heat, and adjust the outdoor temperature at which the heat pump compressor will no longer be used, for example, in response to utility costs or solar production in a hybrid system. A hybrid system refers to a system that does not use electricity for the auxiliary heat (natural gas, propane, etc.). This applies more to air source heat pumps than geothermal.

Switch

The Auxiliary heat only switch is provided to disable the use of the compressor (heat pump), only using the auxiliary heater. Be careful with this setting, as it can incur additional utility costs from using a less-efficient heat source.

Number

The Compressor minimum temperature number represents the outdoor temperature at which the compressor (heat pump) will not run. This is represented in the temperature units you have selected in Home Assistant; however, ecobee allows configuration only in increments of 5 degrees Fahrenheit. This is also represented in the thermostat user interface. When the outdoor temperature is below this value, only auxiliary heat will be used. Be careful with this setting, as it can incur additional utility costs from using a less-efficient heat source.

Check your heat pump Owners’ Manual prior to adjusting this value; do not adjust it below the rated minimum operating temperature of the heat pump. Failure to observe the rated minimum operating temperature can cause damage to the system

Actions

Besides the standard actions provided by the Home Assistant Climate integration, the following extra actions are provided by the ecobee integration:

  • ecobee.create_vacation
  • ecobee.delete_vacation
  • ecobee.resume_program
  • ecobee.set_fan_min_on_time
  • ecobee.set_dst_mode
  • ecobee.set_mic_mode
  • ecobee.set_occupancy_modes
  • ecobee.set_sensors_in_climate

Action: Create vacation

The ecobee.create_vacation action allows you to create a vacation on the selected ecobee thermostat.

Data attribute Optional Description
entity_id no ecobee thermostat on which to create the vacation
vacation_name no Name of the vacation to create. Must be unique on the thermostat
cool_temp no Cooling temperature during the vacation
heat_temp no Heating temperature during the vacation
start_date yes Date the vacation starts in YYYY-MM-DD format
start_time yes Time the vacation starts in the local time zone. Must be in 24-hour format (HH:MM:SS)
end_date yes Date the vacation ends in YYYY-MM-DD format (14 days from now if not provided)
end_time yes Time the vacation ends in the local time zone. Must be in 24-hour format (HH:MM:SS)
fan_mode yes Fan mode of the thermostat during the vacation (auto or on) (auto if not provided)
fan_min_on_time yes Minimum number of minutes to run the fan each hour (0 to 60) during the vacation (0 if not provided)

Action: Delete vacation

The ecobee.delete_vacation action allows you to delete a vacation on the selected ecobee thermostat.

Data attribute Optional Description
entity_id no ecobee thermostat on which to delete the vacation
vacation_name no Name of the vacation to delete

Action: Resume program

The ecobee.resume_program action allows you to resume the standard active schedule of presets. This cancels any manual temperature settings or selected preset. This will not cancel vacation events, use delete_vacation.

Data attribute Optional Description
entity_id yes String or list of strings that point at entity_ids of climate devices to control. Omit to target all ecobee thermostats.
resume_all no true will resume the standard schedule. false will only cancel the latest active event, which is not used often.

Action: Set fan minimum on time

The ecobee.set_fan_min_on_time action allows you to set the minimum amount of time that the fan will run per hour.

Data attribute Optional Description
entity_id yes String or list of strings that point at entity_id’s of climate devices to control. Omit to target all ecobee thermostats.
fan_min_on_time no integer (e.g., 5)

Action: Set DST mode

The ecobee.set_dst_mode action allows you to enable/disable automatic daylight savings time.

Data attribute Optional Description
entity_id yes ecobee thermostat on which to set daylight savings time mode. Omit to target all ecobee thermostats.
dst_enabled no true or false

Action: Set mic mode

The ecobee.set_mic_mode action allows you to enable/disable the Alexa mic (only for ecobee 4).

Data attribute Optional Description
entity_id yes ecobee thermostat on which to set the mic mode. Omit to target all ecobee thermostats.
mic_enabled no true or false

Action: Set occupancy modes

The ecobee.set_occupancy_modes action allows you to enable/disable Smart Home/Away and Follow Me modes.

Data attribute Optional Description
entity_id yes ecobee thermostat on which to set occupancy modes. Omit to target all ecobee thermostats.
auto_away yes true or false
follow_me yes true or false

Action: Set sensors in climate

The ecobee.set_sensors_in_climate action allows you to set which sensors are active on a thermostat for a specific climate program.

Service data attribute Optional Description
entity_id no ecobee thermostat on which to set the active sensors.
preset_mode yes Name of the climate program to set the sensors active on (defaults to currently active program).
sensors no Sensors to set as participating for climate. This is the device ID of the sensor/thermostat. These can be found in the available_sensors attribute.