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 .