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

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