Uptime Kuma
The Uptime Kuma integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] connects Home Assistant with your Uptime Kuma monitoring tool.
About Uptime Kuma
Uptime Kuma is an open-source, free, and easy-to-use self-hosted monitoring tool used to track the uptime and performance of websites, applications, and other services.
How you can use this integration
This integration allows you to track the status of your Uptime Kuma monitors directly in Home Assistant. You can use these entities in dashboards, automations, and scripts to react to service outages or monitor uptime trends within your smart home setup.
Prerequisites
To set up the Uptime Kuma integration, you need an API key and the URL of your Uptime Kuma instance (for example: https://uptime.example.org
).
You can create an API key by logging into your Uptime Kuma instance, navigating to
Configuration
To add the Uptime Kuma integration to your Home Assistant instance, use this My button:
Manual configuration steps
If the above My button doesn’t work, you can also perform the following steps manually:
-
Browse to your Home Assistant instance.
-
In the bottom right corner, select the
Add Integration button. -
From the list, select Uptime Kuma.
-
Follow the instructions on screen to complete the setup.
Sensors
- Status: The current status of the monitor. Possible states: up, down, pending, or maintenance.
- Response time: Time in milliseconds taken for the last status check.
- Certificate expiry: Number of days remaining before the SSL certificate expires.
- Monitor type: The type of check being performed (e.g., HTTP(s), TCP, ping).
- Monitored hostname: The hostname or IP address being monitored (if applicable).
- Monitored port: The port number used by the monitored service (if applicable).
- Monitored URL: The full URL of the monitored service (if applicable).
Update
-
Uptime Kuma version: The update entity indicates if Uptime Kuma is up-to-date or if there is a newer Uptime Kuma version available. For more information on how to update your Uptime Kuma instance, please refer to the documentation
. If you are using the Uptime Kuma community add-on, you will receive an update notification in Home Assistant as soon as the add-on is updated.
Automations
Get started with this automation example to create an Uptime Kuma warning light that changes color based on the monitor’s status.
Example YAML configuration
actions:
- choose:
- conditions:
- condition: state
entity_id: sensor.uptime_kuma_my_service
state: down
sequence:
- action: light.turn_on
data:
color_name: red
target:
entity_id: light.warning_light
- conditions:
- condition: state
entity_id: sensor.uptime_kuma_my_service
state: pending
sequence:
- action: light.turn_on
data:
color_name: yellow
target:
entity_id: light.warning_light
- conditions:
- condition: state
entity_id: sensor.uptime_kuma_my_service
state: maintenance
sequence:
- action: light.turn_on
data:
color_name: blue
target:
entity_id: light.warning_light
- conditions:
- condition: state
entity_id: sensor.uptime_kuma_my_service
state: up
sequence:
- action: light.turn_on
data:
color_name: green
target:
entity_id:
- light.warning_light
triggers:
- trigger: state
entity_id:
- sensor.uptime_kuma_my_service
Data updates
This integration retrieves data from your Uptime Kuma instance every 30 seconds.
Known limitations
- Uptime Kuma’s API does not expose unique identifiers for monitors. Because of this, using the same name for multiple monitors will cause only one of them to appear in Home Assistant. Renaming a monitor will result in new entities being created, while the old (stale) entities will remain unless manually removed.
Troubleshooting
The Uptime Kuma integration relies on an active internet connection to communicate with your Uptime Kuma instance, unless it’s running locally. If you encounter issues, verify that your network connection is stable and your Uptime Kuma instance is accessible.
In any case, when reporting an issue, please enable debug logging, restart the integration, and as soon as the issue reoccurs, stop the debug logging again (download of debug log file will start automatically). Further, if still possible, please also download the diagnostics data. If you have collected the debug log and the diagnostics data, provide them with the issue report.
Removing the integration
This integration can be removed by following these steps:
To remove an integration instance from Home Assistant
-
Go to Settings > Devices & services and select the integration card.
-
From the list of devices, select the integration instance you want to remove.
-
Next to the entry, select the three dots
menu. Then, select Delete. -
You can now remove the API key used for Home Assistant from Uptime Kuma, unless it is also used by other integrations or applications.