Node State List Request

The NodeStateListRequest retrieves the current state of one or more nodes in a single call. For each node, you can request a configurable set of state details — such as the connection, operation, control, battery, and power state — and paginate through large result sets.

Preparations

Launch the development client as described in the FlexConnect API — First Steps.
Navigate to http://localhost:8080/ui.
Select the documentation for Node State List Request in the left pane.

Request

Run the NodeStateListRequest using the JSON body below.

Run the request on app/v1/NodeStateListRequest.
Replace the stringValue of each entry in filter.ids with the identifier of one of your nodes.
Adjust the pagination.limit and the detailTypes list to match your use case.

Request body

json

{
  "header": {
    "reqId": 1234,
    "timeoutMs": 10000
  },
  "pagination": {
    "limit": 100
  },
  "filter": {
    "ids": [
      { "type": { "id": 2 }, "stringValue": "356C2F687081150182505CCCC11BC5C461B60B53" },
      { "type": { "id": 2 }, "stringValue": "54F2664E28EDF2593B9CAAAF041687BEDB0A15C8" },
      { "type": { "id": 2 }, "stringValue": "50F6ED70B16F6846D296AD29F0530B4A3008F529" },
      { "type": { "id": 2 }, "stringValue": "6D60D12A3688E7D2CA3F2C0BD8D5BA01459E9E10" },
      { "type": { "id": 2 }, "stringValue": "870673858C4F56FB3C26550C6CA4CFDA43F45606" }
    ]
  },
  "detailTypes": [1, 2, 3, 4, 5, 6]
}

Request fields

Field	Description
`header.reqId`	Client-defined identifier for the request. The same value is returned in the response header to correlate requests and responses.
`header.timeoutMs`	Maximum time (in milliseconds) the platform waits for the result before responding with a timeout error.
`pagination.limit`	Maximum number of node states returned in a single response. Use the cursor returned in the response to iterate through larger result sets.
`filter.ids`	List of node identifiers to query. All identifiers must be of the same type. The identifiers in the response are returned in the same type.
`detailTypes`	List of optional state details to include for each node. Only the requested details are populated in the response.

Identifier type

The type.id value of 2 refers to the SKI identifier. Use the identifier type that matches the values you have for your nodes.

`detailTypes` values

The detailTypes array selects which optional state attributes are returned for each node. Any combination can be requested.

Value	Code	Description
1	`CONNECTION_STATE`	Whether the node is currently connected to the platform.
2	`OPERATION_STATE`	Whether the node is in normal operation, in a failure state, or in service mode.
3	`CONTROL_STATE`	The control state of the energy storage system (idle, failsafe, power, local, regulated).
4	`BATTERY_STATE`	Current capacity, maximum usable capacity, and state of health of the battery. Only populated when the node is connected.
5	`POWER_STATE`	Desired power setpoint, current active power, and the identifier of the schedule currently in effect. Only populated when the node is connected.
6	`UPTIME_SECONDS`	Uptime of the node in seconds since its last restart.

Response

Response body

json

{
  "header": {
    "reqId": 1234
  },
  "pagination": {
    "cursorNext": "1wsf="
  },
  "nodeStates": [
    {
      "id": {
        "type": { "id": 2 },
        "stringValue": "356C2F687081150182505CCCC11BC5C461B60B53"
      },
      "connectionState": {
        "state": 1,
        "timestamp": 1740268800000
      },
      "operationState": {
        "state": 1,
        "timestamp": 1740268800000
      },
      "controlState": {
        "state": 3,
        "timestamp": 1740268800000
      },
      "batteryState": {
        "state": {
          "currentCapacity": { "number": 1677 },
          "maximumUsableCapacity": { "number": 1842 },
          "stateOfHealth": { "number": 912, "scale": -1 }
        },
        "timestamp": 1740268800000
      },
      "powerState": {
        "state": {
          "desiredPowerSetpoint": { "number": 600 },
          "currentActivePower": { "number": 500 },
          "scheduleId": 582
        },
        "timestamp": 1740268800000
      },
      "uptimeSeconds": 62415
    }
  ]
}

Response fields

Each entry in nodeStates represents a single node. The optional state attributes (connectionState, operationState, controlState, batteryState, powerState, uptimeSeconds) are only included if their corresponding value was specified in the detailTypes of the request.

Connection-dependent values

The batteryState and powerState attributes are only populated when the node's connectionState is CONNECTED.

`connectionState.state` values

Value	Code	Description
1	`CONNECTED`	The node is connected to the platform.
2	`DISCONNECTED`	The node is disconnected from the platform.
3	`PROVISIONED`	The node has been provisioned but has never connected to the platform.

`operationState.state` values

Value	Code	Description
1	`NORMAL_OPERATION`	All systems are operating normally.
2	`FAILURE`	One or more systems are in a failed state.
3	`SERVICE`	The system is in service mode.

`controlState.state` values

Value	Code	Description
1	`IDLE`	The ESS has no active control instructions.
2	`FAILSAFE`	The ESS is in the failsafe state and cannot operate due to a failure.
3	`POWER`	The ESS is in the power control state. Charge and discharge commands are defined by the active schedule with the highest priority.
4	`LOCAL`	The ESS is in the PCC (Point of Common Coupling) control state.
5	`REGULATED`	A regulation authority (such as a grid operator) is in control of the ESS.

`batteryState.state`

Element	Description
`currentCapacity`	Currently available battery capacity in Watt-hours, taking the configured state-of-charge limits into account.
`maximumUsableCapacity`	Maximum usable battery capacity in Watt-hours, taking the configured state-of-charge limits into account. This value decreases over time as the battery degrades.
`stateOfHealth`	State of health of the battery in percent.

All values are represented as scaled numbers — the actual value equals number × 10^scale (a missing scale is treated as 0).

`powerState.state`

Element	Description
`desiredPowerSetpoint`	Desired power setpoint in Watts as specified by the active power schedule. Positive values represent charging, negative values represent discharging.
`currentActivePower`	Currently measured active power in Watts at the grid connection point. May differ from the setpoint due to battery constraints. Positive values represent charging, negative values discharging.
`scheduleId`	Identifier of the schedule currently applied. A value of `0` means that no schedule is currently applied; `-1` means that no schedule can be applied due to a failure.

Pagination

When the requested result set is larger than the pagination.limit, the response includes a pagination.cursorNext value (and, when iterating, a cursorPrevious value).

To retrieve the next page, repeat the request and pass the received cursorNext value as pagination.cursorValue. Iteration ends when no further cursor is returned.

json

{
  "header": {
    "reqId": 1235,
    "timeoutMs": 10000
  },
  "pagination": {
    "limit": 100,
    "cursorValue": "1wsf="
  },
  "filter": {
    "ids": [{ "type": { "id": 2 }, "stringValue": "356C2F687081150182505CCCC11BC5C461B60B53" }]
  },
  "detailTypes": [1, 2, 3, 4, 5, 6]
}

Reducing payload size

Only request the detailTypes you actually need. For example, when periodically polling for liveness, requesting just CONNECTION_STATE (1) significantly reduces the response payload.

Node State List Request ​

Preparations ​

Request ​

Request fields ​

detailTypes values ​

Response ​

Response fields ​

connectionState.state values ​

operationState.state values ​

controlState.state values ​

batteryState.state ​

powerState.state ​

Pagination ​

Node State List Request

Preparations

Request

Request fields

`detailTypes` values

Response

Response fields

`connectionState.state` values

`operationState.state` values

`controlState.state` values

`batteryState.state`

`powerState.state`

Pagination