MQTT export data model and payload format

This technical page describes the exact MQTT API of the MQTT export feature. Use this format when you build a subscriber, parser, or data pipeline that consumes EnergyID messages.

Ready to link your broker to EnergyID? For configuration steps, permissions, and error messages, go to MQTT export.

Core concepts

• Workspace: the environment of an organization in EnergyID.
• Record: a file within a Workspace, usually a building or installation.
• Meter: a time series within a record, for example gas consumption, solar production, or battery storage.
• Device (twin): a connected device or data point that can provide real-time messages.
• Channel: a measurement channel within device data (key-value), for example power, voltage, current, or temperature.

Which data streams exist?

• Meter data: processed meter readings from the record. This data is not real time and is published periodically. The frequency depends on the integration and the meter type.
• Device data: real-time device data per connection/integration. Not all integrations provide real-time data; some integrations only publish meter data.

All device data is also published as meter data, possibly aggregated after processing, but not all meter data is published as device data because not all integrations provide real-time input. For analysis, meter data is therefore the better choice because it is more complete. If you want to build a real-time dashboard, use device data instead.

Meter data

Default topic: energyid/workspace/{{workspaceId}}/record/{{recordNumber}}/meter/{{meterId}}

Meter data is published as a JSON object containing metadata and a data array.

{
  "workspaceId": "7e8f2f7e-2c9f-4e90-bf2e-8e1c6b6f5f6c",
  "recordNumber": "EA-1234567",
  "meterId": "3c2a6b8f-7f0a-45b4-9d4a-6f73b30e30aa",
  "metric": "electricityImport",
  "unit": "kWh",
  "readingType": "PostmarkedInterval",
  "interval": "PT15M",
  "data": [
    {
      "timestamp": "2026-08-06 10:15:00+02:00",
      "value": 1.42,
      "min": 1.21,
      "max": 1.55,
      "mean": 1.39
    }
  ]
}

Fields

• workspaceId: GUID of the Workspace.
• recordNumber: record number.
• meterId: GUID of the meter.
• metric: metric code indicating what is being measured.
• unit: the unit associated with that metric.
• readingType: measurement type, clarifying how a value should be interpreted, for example Counter or Gauge.
• interval: ISO-8601 measurement periodicity, for example PT5M, PT15M, PT1H, P1D, or manual for non-periodic measurements.
• data[].timestamp: timestamp with offset.
• data[].value: main measurement value.
• data[].min / max / mean: only relevant for gauge-like data; may be missing or null for other types.

Important: The fields metric, unit, and readingType are Enums, so there is a fixed set of possible values. For an up-to-date overview of all possible values, see the meter resource API documentation: EnergyID API reference - Meters.

Device data

Default topic: energyid/workspace/{{workspaceId}}/record/{{recordNumber}}/device/{{twinId}}

Device data is published per event as JSON.

{
  "recordNumber": "R-1234567",
  "twinId": "f2a13f6d-1d7a-4f14-b5e8-a53c9f638f1c",
  "timestamp": 1754477700,
  "channels": {
    "pwr": 430.2,
    "el": 230.1
  }
}

Fields

• recordNumber: record number.
• twinId: GUID of the device/digital twin.
• timestamp: Unix timestamp (seconds).
• channels: key-value map with measurement channels and numeric values.

Channels in detail

The exact keys in channels depend on the device type and the connected integration. EnergyID treats channels as a flexible measurement set, so the key set can differ per message or per device type.

Typical channel properties:

• Each key is a measurement name, for example el, pwr, bat, or heat.
• Each value is numeric (floating point).
• Not all keys are always present; subscribers must handle missing or extra keys defensively.
• The meaning and unit of a channel key depend on the integration and device type.

Below is a list of standard channels and how we map them in our systems:

QoS and retain behavior

• Messages are published with QoS AtLeastOnce (QoS 1).
• For meter data, the publisher uses a retain flag so the latest known payload can be kept on the topic by the broker.
• For real-time device data, messages are published without retain.

Errors and robustness

• On connection or publish failures, EnergyID logs a broker-specific delivery failure in the Workspace settings.
• After a failure, the publisher retries using a fresh connection.
• On the first failure, a Workspace administrator receives a message in the message center.