Documentation

Flex

Copy page

TL;DR

• GET /v1/users/{userId}/flex/forecast — the quarter-hourly energy forecast together with the controllable energy flexibility, in one read-only request.
• Each slot is an Energy Forecast slot plus a flex band with home totals and an asset-class breakdown; currently home batteries (powerStorage) contribute.
• Forecast and flexibility come from the same calculation, so the band always refers to the forecast values in the same slot.
• Energy is in kWh per slot, prices in ct/kWh, power in kW, capacity in kWh, state of charge in percent, and timestamps in UTC.

Flex helps partners assess how much additional grid draw a battery pool can absorb and how much baseline charging can be reduced. It provides a consistent view across eligible home batteries for flexibility analysis and planning. It does not reserve capacity, dispatch devices, or guarantee delivered power.

The dedicated Flex API group keeps this capability separate from Solar Forecast and Energy Forecast. The existing internal energy calculation supplies both the forecast baseline and the flexibility band, and both are returned from the same calculation snapshot. You do not need a separate Energy Forecast call to interpret the band. The inverter's export-limit setting is a separate control capability.

Flex resources are nested below the user at /v1/users/{userId}/flex. Currently, /v1/users/{userId}/flex/forecast is the only Flex endpoint, and it is read-only.

Get forecast and flexibility

GET /v1/users/{userId}/flex/forecast

Code
GET /v1/users/3f9b1c7a-.../flex/forecast
Authorization: Bearer eyJhbGciOi...

No flexibility query parameter is needed. Authentication uses the same bearer token and connect_api scope as the other Connect API endpoints.

200 OK

Code
{
  "createdAtUtc": "2026-09-18T11:52:02Z",
  "entries": [
    {
      "time": "2026-09-18T11:45:00Z",
      "price": 24.8,
      "stockPrice": 6.1,
      "houseConsumptionKwh": 0.18,
      "solarProductionKwh": 1.25,
      "soc": 50,
      "gridConsumptionKwh": 0,
      "gridFeedInKwh": 0.57,
      "flex": {
        "addableLoadKw": 6,
        "reducibleLoadKw": 2,
        "availableChargeCapacityKwh": 5,
        "installedCapacityKwh": 10,
        "baselineBatteryPowerKw": 2,
        "stateOfChargePercent": 50,
        "state": "charging",
        "classes": {
          "powerStorage": {
            "addableLoadKw": 6,
            "reducibleLoadKw": 2,
            "availableChargeCapacityKwh": 5,
            "installedCapacityKwh": 10,
            "baselineBatteryPowerKw": 2,
            "stateOfChargePercent": 50,
            "state": "charging"
          }
        }
      }
    },
    {
      "time": "2026-09-18T12:00:00Z",
      "price": null,
      "stockPrice": null,
      "houseConsumptionKwh": 0.2,
      "solarProductionKwh": 1.21,
      "soc": 55,
      "gridConsumptionKwh": 0,
      "gridFeedInKwh": 0.51,
      "flex": null
    }
  ]
}

Field	Type	Meaning
createdAtUtc	string	Time of the underlying calculation, UTC ISO-8601.
entries	array	Forward-looking, 15-minute slots ordered by time.
entries[].time	string	Start of the slot, UTC ISO-8601.
entries[].price … entries[].gridFeedInKwh		The forecast fields of the slot, identical to the Energy Forecast slot.
entries[].flex	object or null	Home flexibility totals and asset classes. null means the underlying service supplied no band for this slot; do not treat it as available flexibility.

Each slot’s flex object contains home totals. classes is keyed by asset class and contains the same values for each class in scope. It can be empty when no assets are present. Today the only key is powerStorage; further asset classes may be added later, so ignore keys you do not know. No individual battery IDs or per-device values are exposed.

Field	Unit	Meaning
addableLoadKw	kW	Additional grid draw available above the forecast baseline for this slot.
reducibleLoadKw	kW	Grid draw that can be reduced from baseline charging. This is not a promise of additional battery discharge or grid export.
availableChargeCapacityKwh	kWh	Free charge capacity of contributing batteries at the start of the slot.
installedCapacityKwh	kWh	Capacity currently eligible to contribute, not the nameplate capacity of every installed battery.
baselineBatteryPowerKw	kW	Signed baseline battery power: positive = charging, negative = discharging.
stateOfChargePercent	% or null	Capacity-weighted SoC of contributing batteries at slot start. Can differ from entries[].soc in the same slot. null when none contribute.
state	string	unavailable, ready, charging, full, or discharging.

Availability and interpretation: Only controllable batteries with known positive capacity, sufficiently recent telemetry (less than 15 minutes old), and a usable pool state contribute. Excluded batteries contribute zero, including to installedCapacityKwh. If no battery contributes, the band remains present with zero power/capacity values, stateOfChargePercent: null, and state: "unavailable". An excluded class can remain in classes with unavailable/zero values.

ready means a contributing pool has free capacity and no material baseline charging/discharging; charging and discharging follow the signed baseline. full indicates no remaining charge capacity unless the pool is already discharging. States are computed at each aggregation level, so opposing flows can cancel in home totals.

Planning limits: The current calculation uses a default charge-power estimate of 0.8C (8 kW for 10 kWh) and limits the offered power to what can be sustained over the 15-minute slot. Values are a band around the existing baseline; they are not independently repeatable offers for every slot. An intervention changes subsequent SoC and available flexibility, so refresh the forecast when planning further actions.

Current prerequisites

The existing internal calculation and checks are unchanged: a home with a location, at least one producing device, and enabled Solar Forecast is currently required. Configure these via the Solar Forecast endpoints. The separate Flex route does not introduce an independent enable switch.

Error responses

All errors follow RFC 7807 (application/problem+json) using the partner-friendly ConnectApiProblemDetails shape (type + errorCode + traceId + optional detail).

Status	errorCode	Meaning
401	—	Missing or invalid bearer token.
403	—	Token lacks the connect_api scope.
404	missingHome	The authenticated user has no home.
404	solarForecastNotAvailable	The forecast is enabled and prerequisites are met, but it has not been generated yet. Retry shortly.
409	homeLocationRequired	No home location is set. Call PUT …/home/location first.
409	solarProducerRequired	The home has no producing device (inverter/meter); a forecast cannot be generated.
409	solarForecastDisabled	The forecast is disabled. Enable it via PUT …/home/solar-forecast to regenerate.
429	—	Rate limit exceeded, see Rate limits.
500	internalError	Unhandled server error.

Migration from the beta query flag

Replace GET …/home/energy-forecast?flexibility=true with GET /v1/users/{userId}/flex/forecast and read the forecast fields and entries[].flex from the Flex response. Its slots have the same forecast fields as Energy Forecast plus flex, so a single request replaces the former flagged call. The Energy Forecast route no longer supports the flexibility flag: ?flexibility=true is ignored and the response never includes a flex field.