Prometheus sensor for Home Assistant

Use PromQL expressions to query Prometheus-compatible APIs and expose the results as sensor values in Home Assistant.

Contributions welcome!

Compatibility

Tested against Home Assistant 2026.1.1.

Basic setup

This component hooks into Home Assistant via the YAML configuration as a platform integration. The platform can be defined multiple times with varying settings.

Settings

Name	Type	Required	Example	Description
platform	string	true	prometheus_sensor	Platform name
url	string	true	http://localhost:9090	Prometheus base URL
headers	mapping	false	Extra HTTP headers	Extra HTTP headers
queries	list	true	Example	List of queries to execute

Extra HTTP headers

This is an optional mapping (string -> string) that will be sent with every request. It can be used to support authentication headers or tenant selection in Grafana Mimir.

sensor:
  - platform: prometheus_sensor
    url: http://localhost:8080
    headers:
      # Grafana Mimir tenant selection
      X-Scope-OrgID: my-tenant
      # Avoid hardcoding secrets, use !secret in production
      Authorization: Bearer <token>

Entities

This component currently supports sensor and binary_sensor entities. Each query is represented as one entity in Home Assistant.

Binary Sensor

Name	Type	Default	Description
name	string	required	Friendly name
unique_id	string	optional	Unique ID
expr	string	required	PromQL expression
value_template	string	optional	Template
device_class	string	optional	Device class (binary sensor)

The binary sensor uses a naive bool() cast on the value or, if configured, the result of the template expression. This means that the sensor will be off, when the query returns 0 or 0.0 and on in every other case.

Sensor

Name	Type	Default	Description
name	string	required	Friendly name
unique_id	string	optional	Unique ID
expr	string	required	PromQL expression
unit_of_measurement	string	optional	Unit of the measurement
device_class	string	optional	Device class (sensor)
state_class	string	optional	State class

Example usage

binary_sensor:
  - platform: prometheus_sensor
    url: http://localhost:9090
    queries:
      - name: Front Door
        unique_id: front_door_open
        expr: front_door_open
        value_template: "{{ value == 1 }}"
        device_class: door

sensor:
  - platform: prometheus_sensor
    url: http://localhost:9090
    queries:
      - name: Energy usage
        expr: energy_usage_wh / 1000
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
      - name: Energy solar production
        expr: energy_solar_wh / 1000
        unit_of_measurement: kWh
        device_class: energy
        state_class: total_increasing
      - name: Energy grid consumption
        unit_of_measurement: kWh
        expr: energy_grid_wh / 1000
        device_class: energy
        state_class: total_increasing

Upstream integration

I tried to get this component merged into home-assistant in 2020/12.

home-assistant/core#44508

That effort failed when the requirement to create a third party library to handle the interaction with the Prometheus API came up.

The code is using async aiohttp calls and reuses the home-assistant internal aiohttp client session. At the time I did not find a ready to use async prometheus client library, and the search for one wasn't easy due to the term client being overloaded in the Prometheus world. I was also not going to start maintaining such a library, when the class to wrap the Prometheus instant query API was a mere 36 LoC.

Everyone is welcome to pick up this effort!