Topology

The Site Topology endpoint provides a full description of the devices at a site and how they are connected together. It is available on both the Partner and Customer APIs:

Partner API: GET /api/v1/sites/{siteId}/topology
Customer API: GET /api/v1/sites/{siteId}/topology

The response shape is identical across both APIs.

How topology is structured

The topology is a tree rooted at the site. Each node in the tree represents a physical or logical element: a site, a home controller, an inverter, a battery management system (BMS), a PV array, a grid connection point, or similar.

Nodes with "kind": "sensor" are particularly important — their id is the stream key used to query the Telemetry endpoint. Each sensor node also exposes a channels array listing the data channels available for that stream (e.g. power_W, soc, energy_Wh_increment).

{
  "kind": "sensor",
  "id": "lunar_hc-yyy-inv-1__bb_agg",
  "nodeType": "neutral",
  "channels": [
    { "id": "power_W", "unit": "W" },
    { "id": "soc", "unit": "percent" },
    { "id": "energy_Wh_increment", "unit": "Wh" },
    { "id": "energy_Wh_decrement", "unit": "Wh" }
  ],
  "node": {
    "id": "lunar_hc-yyy-inv-1__bb_agg",
    "kind": "BMS",
    "nodeType": "source-sink",
    "maxCapacity_J": 36000000
  }
}

ℹ️
Do not parse the ID string to infer device type or structure. Use the kind, category, and nodeType fields instead. The ID format may vary by manufacturer.

Compact vs. expanded topology

The compact query parameter (default true) controls how multi-device subsystems are represented:

	`compact=true`	`compact=false`
Battery blocks	Aggregated into a single `__bb_agg` BMS node	One BMS node per physical battery block
PV optimisers	Aggregated into a single `__dcm` PV-array node	One PV-array node per optimiser

When using compact=true some sensor nodes represent synthetic (aggregated) devices. For example, querying telemetry for the __bb_agg BMS node returns aggregate values across all battery blocks at the site, not a single block.

Compact example — a system with two battery blocks appears as one aggregate node:

{
  "id": "lunar_hc-XXX-inv-XXX__bb_agg",
  "kind": "BMS",
  "nodeType": "source-sink",
  "maxCapacity_J": 36000000
}

You can use the maxCapacity_J field to determine the capacity of the entire system.

Expanded example — the same system shows each block separately:

[
  { "id": "lunar_hc-xxx-bb-1", "kind": "BMS", "nodeType": "source-sink", "maxCapacity_J": 18000000 },
  { "id": "lunar_hc-xxx-bb-2", "kind": "BMS", "nodeType": "source-sink", "maxCapacity_J": 18000000 }
]

You can use the maxCapacity_J field of each BMS node to determine the capacity of each battery block individually.

The compact representation is recommended for most integrations. Telemetry queried using the aggregate __bb_agg sensor ID returns values that represent the entire battery, not a single block.

Recommended workflow

To retrieve telemetry for all sensors at a site:

Call GET /api/v2/sites to list the customer's site IDs.
Call GET /api/v1/sites/{siteId}/topology to get the site's topology tree.
Walk the tree and collect every node where "kind": "sensor". Each node's id is a queryable telemetry stream and its channels array lists which channels are available.
Call GET /api/v1/devices/{sensorId}/telemetry for each sensor ID.

Examples

Example full topology of a site with one inverter, 2 battery blocks, and 3 PV arrays (compact=false):

{
  "topology": {
    "id": "site-xxx",
    "category": "site",
    "currentType": "AC-split-phase",
    "nodes": [
      {
        "id": "lunar_hc-yyy",
        "category": "logical",
        "currentType": "AC-split-phase",
        "nodes": [
          {
            "id": "lunar_hc-yyy-inv-1",
            "kind": "sensor",
            "nodeType": "neutral",
            "channels": [
              { "id": "power_AC_W", "unit": "W" },
              { "id": "power_DC_W", "unit": "W" },
              { "id": "energy_Wh_increment", "unit": "Wh" },
              { "id": "energy_Wh_decrement", "unit": "Wh" }
            ],
            "node": {
              "id": "lunar_hc-yyy-inv-1",
              "leftCurrent": "AC-split-phase",
              "rightCircuit": {
                "id": "lunar_hc-yyy-inv-1-dc-circuit",
                "category": "behind-inverter",
                "currentType": "DC",
                "nodes": [
                  {
                    "id": "lunar_hc-yyy-bb-1",
                    "kind": "sensor",
                    "nodeType": "neutral",
                    "channels": [
                      { "id": "power_W", "unit": "W" },
                      { "id": "soc", "unit": "percent" },
                      { "id": "soh", "unit": "percent" },
                      { "id": "energy_Wh_increment", "unit": "Wh" },
                      { "id": "energy_Wh_decrement", "unit": "Wh" }
                    ],
                    "node": {
                      "id": "lunar_hc-yyy-bb-1",
                      "kind": "BMS",
                      "nodeType": "source-sink",
                      "maxCapacity_J": 18000000
                    }
                  },
                  {
                    "id": "lunar_hc-yyy-bb-2",
                    "kind": "sensor",
                    "nodeType": "neutral",
                    "channels": [
                      { "id": "power_W", "unit": "W" },
                      { "id": "soc", "unit": "percent" },
                      { "id": "soh", "unit": "percent" },
                      { "id": "energy_Wh_increment", "unit": "Wh" },
                      { "id": "energy_Wh_decrement", "unit": "Wh" }
                    ],
                    "node": {
                      "id": "lunar_hc-yyy-bb-2",
                      "kind": "BMS",
                      "nodeType": "source-sink",
                      "maxCapacity_J": 18000000
                    }
                  },
                  {
                    "id": "lunar_hc-yyy-pvhub-1",
                    "category": "logical",
                    "currentType": "DC",
                    "nodes": [],
                    "nodeType": "source-sink",
                    "kind": "circuit"
                  },
                  {
                    "id": "lunar_hc-yyy-pvo-1",
                    "kind": "sensor",
                    "nodeType": "neutral",
                    "channels": [
                      { "id": "power_W", "unit": "W" },
                      { "id": "energy_Wh_decrement", "unit": "Wh" }
                    ],
                    "node": { "id": "lunar_hc-yyy-pvo-1", "kind": "PV-array", "nodeType": "source" }
                  },
                  {
                    "id": "lunar_hc-yyy-pvo-2",
                    "kind": "sensor",
                    "nodeType": "neutral",
                    "channels": [
                      { "id": "power_W", "unit": "W" },
                      { "id": "energy_Wh_decrement", "unit": "Wh" }
                    ],
                    "node": { "id": "lunar_hc-yyy-pvo-2", "kind": "PV-array", "nodeType": "source" }
                  },
                  {
                    "id": "lunar_hc-yyy-pvo-3",
                    "kind": "sensor",
                    "nodeType": "neutral",
                    "channels": [
                      { "id": "power_W", "unit": "W" },
                      { "id": "energy_Wh_decrement", "unit": "Wh" }
                    ],
                    "node": { "id": "lunar_hc-yyy-pvo-3", "kind": "PV-array", "nodeType": "source" }
                  }
                ],
                "nodeType": "source-sink",
                "kind": "circuit"
              },
              "kind": "inverter",
              "nodeType": "source-sink"
            }
          }
        ],
        "nodeType": "source-sink",
        "kind": "circuit"
      },
      {
        "id": "lunar_hc-yyy-gip-1",
        "kind": "sensor",
        "nodeType": "neutral",
        "channels": [
          { "id": "power_W", "unit": "W" },
          { "id": "state", "unit": "None" },
          { "id": "energy_Wh_increment", "unit": "Wh" },
          { "id": "energy_Wh_decrement", "unit": "Wh" }
        ],
        "node": {
          "id": "lunar_hc-yyy-gip-1",
          "leftCurrent": "AC-split-phase",
          "rightCircuit": {
            "id": "grid",
            "category": "grid",
            "currentType": "AC-three-phase",
            "nodes": [],
            "nodeType": "source-sink",
            "kind": "circuit"
          },
          "kind": "connection-point",
          "nodeType": "neutral"
        }
      }
    ],
    "nodeType": "source-sink",
    "kind": "circuit"
  }
}

Example compact topology of the same site (compact=true):

{
  "topology": {
    "id": "site-xxx",
    "category": "site",
    "currentType": "AC-split-phase",
    "nodes": [
      {
        "id": "lunar_hc-yyy",
        "category": "logical",
        "currentType": "AC-split-phase",
        "nodes": [
          {
            "id": "lunar_hc-yyy-inv-1",
            "kind": "sensor",
            "nodeType": "neutral",
            "channels": [
              { "id": "power_AC_W", "unit": "W" },
              { "id": "power_DC_W", "unit": "W" },
              { "id": "energy_Wh_increment", "unit": "Wh" },
              { "id": "energy_Wh_decrement", "unit": "Wh" }
            ],
            "node": {
              "id": "lunar_hc-yyy-inv-1",
              "leftCurrent": "AC-split-phase",
              "rightCircuit": {
                "id": "lunar_hc-yyy-inv-1-dc-circuit",
                "category": "behind-inverter",
                "currentType": "DC",
                "nodes": [
                  {
                    "id": "lunar_hc-yyy-inv-1__bb_agg",
                    "kind": "sensor",
                    "nodeType": "neutral",
                    "channels": [
                      { "id": "power_W", "unit": "W" },
                      { "id": "soc", "unit": "percent" },
                      { "id": "energy_Wh_increment", "unit": "Wh" },
                      { "id": "energy_Wh_decrement", "unit": "Wh" }
                    ],
                    "node": {
                      "id": "lunar_hc-yyy-inv-1__bb_agg",
                      "kind": "BMS",
                      "nodeType": "source-sink",
                      "maxCapacity_J": 36000000
                    }
                  },
                  {
                    "id": "lunar_hc-yyy-pvhub-a0764ef01418",
                    "category": "logical",
                    "currentType": "DC",
                    "nodes": [],
                    "nodeType": "source-sink",
                    "kind": "circuit"
                  },
                  {
                    "id": "lunar_hc-yyy-inv-1__dcm",
                    "kind": "sensor",
                    "nodeType": "neutral",
                    "channels": [
                      { "id": "power_W", "unit": "W" },
                      { "id": "energy_Wh_decrement", "unit": "Wh" }
                    ],
                    "node": {
                      "id": "lunar_hc-yyy-inv-1__dcm",
                      "kind": "PV-array",
                      "nodeType": "source"
                    }
                  }
                ],
                "nodeType": "source-sink",
                "kind": "circuit"
              },
              "kind": "inverter",
              "nodeType": "source-sink"
            }
          }
        ],
        "nodeType": "source-sink",
        "kind": "circuit"
      },
      {
        "id": "lunar_hc-yyy-gip-1",
        "kind": "sensor",
        "nodeType": "neutral",
        "channels": [
          { "id": "power_W", "unit": "W" },
          { "id": "state", "unit": "None" },
          { "id": "energy_Wh_increment", "unit": "Wh" },
          { "id": "energy_Wh_decrement", "unit": "Wh" }
        ],
        "node": {
          "id": "lunar_hc-yyy-gip-1",
          "leftCurrent": "AC-split-phase",
          "rightCircuit": {
            "id": "grid",
            "category": "grid",
            "currentType": "AC-three-phase",
            "nodes": [],
            "nodeType": "source-sink",
            "kind": "circuit"
          },
          "kind": "connection-point",
          "nodeType": "neutral"
        }
      }
    ],
    "nodeType": "source-sink",
    "kind": "circuit"
  }
}

How topology is structured

Do not parse the ID string to infer device type or structure. Use the kind, category, and nodeType fields instead. The ID format may vary by manufacturer.

Compact vs. expanded topology

Recommended workflow

Examples

Do not parse the ID string to infer device type or structure. Use the `kind`, `category`, and `nodeType` fields instead. The ID format may vary by manufacturer.