2025.8.3
Home ▸ Integrations ▸

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 Settings → API Keys and selecting Add API Key.

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.

  • Go to Settings > Devices & Services.

  • 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.

URL

Address of your Uptime Kuma instance. Example: https://uptime.example.com.

Verify SSL certificate

Enable SSL certificate verification for secure connections.

API key

An API key to authenticate with your Uptime Kuma instance.

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

  1. Go to Settings > Devices & services and select the integration card.

  2. From the list of devices, select the integration instance you want to remove.

  3. Next to the entry, select the three dots menu. Then, select Delete.

  4. You can now remove the API key used for Home Assistant from Uptime Kuma, unless it is also used by other integrations or applications.