Gatus

The Gatus integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] connects Home Assistant with your Gatus monitoring instance. Gatus is a developer-oriented health dashboard that lets you monitor your services using HTTP, ICMP, TCP, and DNS queries, and evaluate results based on conditions like status codes, response times, certificate expiration, and response bodies.

Use cases

  • Display the live status of your self-hosted services on a Home Assistant dashboard.
  • Trigger automations or send notifications when a monitored service goes down or comes back up.
  • Combine endpoint status with other Home Assistant entities to coordinate responses to outages, such as switching to a backup service or alerting specific people.

Supported devices

The integration creates a device for each endpoint configured in your Gatus instance under the Gatus service. When endpoints are added or removed in Gatus, the integration dynamically creates or removes the corresponding devices and entities during periodic polling updates.

Prerequisites

You need the base URL of your Gatus instance, for example http://gatus.local:8080 or https://status.example.com.

If your Gatus instance requires authentication, you will also need one of the following:

  • A username and password for HTTP Basic Authentication.
  • An API key (API token or Bearer token).

Configuration

To add the Gatus service 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:

URL

The full base URL of your Gatus status page instance, including the protocol and port. For example: http://gatus.local:8080 or https://status.example.com.

Username

Optional username for HTTP Basic Authentication.

Password

Optional password for HTTP Basic Authentication.

API key

Optional API key (API token or Bearer token) for authentication.

Supported versions

This integration supports Gatus version 5.x.x or higher.

Supported functionality

The Gatus integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following entities.

Binary sensors

For each endpoint configured in Gatus, the integration creates the following binary sensor:

  • Connectivity: Reports on (connected) when the most recent check for that endpoint succeeded, and off (disconnected) when it failed.

Sensors

For each endpoint configured in Gatus, the integration creates the following sensors:

  • Response time: Reports the check latency in milliseconds (ms) of the most recent health check.
  • Status code: Reports the numeric status code of the most recent health check. For HTTP endpoints, this is the HTTP status code.
  • Last event: Reports the most recent event type (start, healthy, unhealthy, or resolved).
  • Certificate expiration: Reports the timestamp when the SSL/TLS certificate expires. Only created for endpoints with certificate monitoring enabled.
  • DNS response code: Reports the DNS query response code (such as no_error, format_error, server_failure, non_existent_domain, not_implemented, refused). Only created for endpoints with DNS monitoring enabled.

Gatus automation examples

Here are a few ideas to get you started.

Tip

You don’t need to edit YAML to use these examples. Copy a YAML snippet from this page, open the visual automation editor in Home Assistant, and press Ctrl+V (or Cmd+V on Mac). Home Assistant automatically converts the pasted YAML into the visual editor format, whether it’s a full automation, a single trigger, a condition, or an action.

Send a notification when a service goes down

Get notified the moment one of your monitored endpoints fails its health check.

To create this automation in the UI:

  1. Go to Settings > Automations & scenes and create a new automation.
  2. Add a State changed trigger.
  3. In Entity, select the Gatus binary sensor for the endpoint you want to monitor.
  4. In To, enter off.
  5. Add the Send a notification message action.
  6. In Target, select the notification entity for your device, for example My Phone (notify.my_phone).
  7. In Message, enter Service {{ trigger.to_state.name }} is down!.
Example YAML configuration
AutomationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more]
alias: "Notify when a Gatus endpoint goes down"
triggers:
  - trigger: state
    entity_id: binary_sensor.my_gatus_endpoint
    to: "off"
actions:
  - action: notify.send_message
    target:
      entity_id: notify.my_phone
    data:
      message: "Service {{ trigger.to_state.name }} is down!"

Send a notification when a service recovers

Get notified when a previously failing endpoint comes back online.

To create this automation in the UI:

  1. Go to Settings > Automations & scenes and create a new automation.
  2. Add a State changed trigger.
  3. In Entity, select the Gatus binary sensor for the endpoint you want to monitor.
  4. In From, enter off.
  5. In To, enter on.
  6. Add the Send a notification message action.
  7. In Target, select the notification entity for your device, for example My Phone (notify.my_phone).
  8. In Message, enter Service {{ trigger.to_state.name }} is back online..
Example YAML configuration
AutomationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [Learn more]
alias: "Notify when a Gatus endpoint recovers"
triggers:
  - trigger: state
    entity_id: binary_sensor.my_gatus_endpoint
    from: "off"
    to: "on"
actions:
  - action: notify.send_message
    target:
      entity_id: notify.my_phone
    data:
      message: "Service {{ trigger.to_state.name }} is back online."

Data updates

The integration pollsData polling is the process of querying a device or service at regular intervals to check for updates or retrieve data. By defining a custom polling interval, you can control how frequently your system checks for new data, which can help optimize performance and reduce unnecessary network traffic. [Learn more] your Gatus instance every 30 seconds.

Defining a custom polling interval

If you want to define a specific interval at which your device is being polled for data, you can disable the default polling interval and create your own polling automation.

To turn off the default polling and create your own polling automation, follow these steps:

  1. Go to Settings > Devices & services, and select your integration.
  2. On the integration entry, select the three dots menu, and then select System options.
  3. Turn off Enable polling for changes, and then select Update.
    • If Home Assistant asks you to restart, restart it.
  4. Go to Settings > Automations & scenes, and select Create automation > Create new automation.
  5. Add the triggers and conditions for when you want to poll for data.
  6. Select Add action, select By type, select Perform action, and then select + next to Perform action.
  7. Under Action, search for and select the Update entity action.
  8. Under Entities to update, select the entities you want to poll.
    • You can only select entities. Areas, devices, and labels aren’t supported.
  9. Select Save.

Many integrations update their data at most once every 10 seconds. If you poll more often, Home Assistant waits until the 10 seconds have passed before it updates the data again.

Reconfiguration

If you need to update the connection details (URL or credentials) of your Gatus instance, you can reconfigure the integration:

  1. Go to Settings > Devices & services.
  2. Select the Gatus integration card.
  3. Select the three dots menu , and then select Reconfigure.
  4. Update the URL or credentials of your Gatus instance.
  5. Select Submit.

Reauthentication

If the credentials for your Gatus instance become invalid, Home Assistant prompts you to re-authenticate:

  1. Go to Settings > Devices & services.
  2. Select Reconfigure on the notification or Gatus integration card.
  3. Enter the updated username/password or API key.
  4. Select Submit.

Known limitations

  • The integration shows the result of the most recent health check. Historical results stored by Gatus are not available as entities.

Troubleshooting

Can’t set up the integration

Symptom: “Unable to connect”

The setup form shows an error saying it cannot connect to your Gatus instance.

Resolution

  1. Confirm your Gatus instance is running and reachable from your Home Assistant host.
  2. Check that the URL you entered is correct and includes the protocol and port, for example http://gatus.local:8080.
  3. If Gatus is behind a reverse proxy or uses HTTPS, make sure the certificate is valid and the URL matches exactly.
  4. Check your firewall rules to confirm Home Assistant is allowed to reach the Gatus host on the configured port.

Symptom: “Invalid authentication”

The setup form shows an error saying authentication failed.

Resolution

  1. If using HTTP Basic Authentication, verify that the username and password are correct.
  2. If using an API key, verify that the key is valid and not expired.

Entities are unavailable

If entities become unavailable after setup, Home Assistant could not reach your Gatus instance during the last data refresh. Check your network connection and confirm the Gatus instance is still running. Entities will recover automatically once the connection is restored.

Diagnostics

The Gatus integration supports diagnostic data collection to help troubleshoot issues. If you’re experiencing problems with the integration, you can download diagnostic information to include when reporting issues.

The diagnostic data contains the status of all Gatus endpoints monitored by the integration. It does not include authentication credentials or sensitive connection parameters.

Removing the integration

This integration follows standard integration removal.

To remove an integration instance from Home Assistant

  1. Go to Settings > Devices & services and select the integration card.
  2. Next to the entry you want to remove, select the three dots menu. Then, select Delete.
    • Depending on the integration, the entries are listed under one of the following headings:
      • Devices
      • Hubs
      • Services
      • Integration entries
  3. To confirm, select Delete.
    • Home Assistant also deletes the devices and entities of the entry.
  4. If Home Assistant asks you to restart, restart Home Assistant.
  5. If Home Assistant asks whether to also delete the application credentials, select Remove or Keep.