octopus_exporter

A Prometheus exporter for Octopus Energy smart meter data, using the Kraken GraphQL API.

Metrics

Electricity

Metric	Source	Description
`octopus_electricity_demand_watts`	GraphQL	Live electricity demand in watts
`octopus_electricity_last_read_timestamp`	GraphQL	Unix timestamp of last electricity reading
`octopus_electricity_consumption_kwh`	REST	Latest half-hourly consumption in kWh
`octopus_electricity_consumption_interval_timestamp`	REST	Unix timestamp of the start of the latest consumption interval
`octopus_electricity_unit_rate_pence`	GraphQL / REST	Current unit rate in pence per kWh (Agile customers get the live half-hourly rate from the REST API)
`octopus_electricity_standing_charge_pence`	GraphQL	Current standing charge in pence per day

Gas

Gas metrics are only exposed if a smart gas meter is found on the account.

Metric	Source	Description
`octopus_gas_demand_watts`	GraphQL	Live gas demand in watts
`octopus_gas_last_read_timestamp`	GraphQL	Unix timestamp of last gas reading
`octopus_gas_consumption_kwh`	REST	Latest half-hourly consumption in kWh
`octopus_gas_consumption_interval_timestamp`	REST	Unix timestamp of the start of the latest gas consumption interval
`octopus_gas_unit_rate_pence`	GraphQL	Current unit rate in pence per kWh
`octopus_gas_standing_charge_pence`	GraphQL	Current standing charge in pence per day

Solar / export

Solar metrics are only exposed if an electricity export meter point (direction EXPORT) is found on the account. Solar export usually shares the physical meter and smart device with the import meter, so live export watts come from the same telemetry call as electricity demand (no extra API request).

Metric	Source	Description
`octopus_solar_export_watts`	GraphQL	Live electricity export to the grid in watts
`octopus_solar_last_read_timestamp`	GraphQL	Unix timestamp of last solar export reading
`octopus_solar_export_kwh`	REST	Latest half-hourly energy exported to the grid in kWh
`octopus_solar_export_interval_timestamp`	REST	Unix timestamp of the start of the latest export interval
`octopus_solar_export_rate_pence`	GraphQL	Current export (outgoing) unit rate in pence per kWh

Account

Metric	Source	Description
`octopus_account_balance_pence`	GraphQL	Account balance in pence (positive = credit, negative = debit)

Exporter health

Metric	Description
`octopus_up`	1 if the last poll cycle completed without errors, 0 otherwise
`octopus_last_poll_timestamp`	Unix timestamp of the last completed poll cycle
`octopus_poll_errors_total`	Total number of collector errors across all poll cycles
`octopus_token_refreshes_total`	Total number of successful JWT token refreshes
`octopus_rate_limit_retries_total`	Total number of 429 rate-limit retries
`octopus_build_info{version,commit}`	Build metadata (always 1)

Metrics are refreshed every POLL_INTERVAL (default 60 seconds).

Configuration

Variable	Required	Description
`OCTOPUS_API_KEY`	Yes	Your Octopus Energy API key
`OCTOPUS_MPAN`	No	Filter electricity meter by MPAN
`OCTOPUS_SERIAL`	No	Filter electricity meter by serial number
`OCTOPUS_DEVICE_ID`	No	Use a specific electricity smart device ID directly
`OCTOPUS_GAS_MPRN`	No	Filter gas meter by MPRN
`OCTOPUS_GAS_SERIAL`	No	Filter gas meter by serial number
`OCTOPUS_GAS_DEVICE_ID`	No	Use a specific gas smart device ID directly
`OCTOPUS_SOLAR_MPAN`	No	Filter solar export meter by MPAN
`OCTOPUS_SOLAR_SERIAL`	No	Filter solar export meter by serial number
`OCTOPUS_SOLAR_DEVICE_ID`	No	Use a specific solar export smart device ID directly
`PORT`	No	Port to expose metrics on (default: `9359`)
`POLL_INTERVAL`	No	How often to poll Octopus APIs (Go duration, default: `60s`)

If no filter variables are set, the exporter auto-discovers the first smart meter of each type found on the account. Use OCTOPUS_MPAN / OCTOPUS_MPRN to pin to a specific meter on accounts with multiple meters.

Your API key can be found in the Octopus Energy developer dashboard.

Docker

docker run -d \
  -e OCTOPUS_API_KEY=sk_live_... \
  -e OCTOPUS_MPAN=1234567890123 \
  -p 9359:9359 \
  rwejlgaard/octopus_exporter

Docker Compose

services:
  octopus-exporter:
    image: rwejlgaard/octopus_exporter:latest
    restart: unless-stopped
    environment:
      OCTOPUS_API_KEY: sk_live_...
      OCTOPUS_MPAN: "1234567890123"   # optional, auto-discovered if omitted
    ports:
      - "9359:9359"

Running from source

Requires Go 1.24+.

git clone https://github.com/rwejlgaard/octopus_exporter
cd octopus_exporter
OCTOPUS_API_KEY=sk_live_... go run ./cmd/octopus_exporter

Prometheus configuration

scrape_configs:
  - job_name: octopus
    static_configs:
      - targets: ['localhost:9359']

Building

go build ./cmd/octopus_exporter

docker build -t rwejlgaard/octopus_exporter .

5.2 KiB Raw Permalink Blame History