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.

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

Request body

{
  "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

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

{
  "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. :::