EBXv1

API reference

Telemetry

Reading back what an asset is doing: its live state, the state history over a window, and the planned state it is scheduled to follow.

3 endpoints
GET/v1/assets/{asset_id}/planned_state

Get asset planned state

asset.read

Get a consolidated planned-state view for an asset over a UTC time window.

Returns a snapshot of all scheduled activities overlapping the requested window:

  • scheduled_dispatch: Wholesale dispatch setpoints from the schedule
  • fcr_reservations: FCR capacity bids with accepted status
  • afrr_capacity_reservations: aFRR capacity bids with accepted status
  • afrr_energy_reservations: aFRR energy bids with accepted status
  • power_limits: Active power limit restrictions
  • energy_limits: Active energy limit restrictions
  • unavailabilities: Scheduled unavailability periods
  • curtailments: Active curtailment intervals

Query Parameters:

  • start_time: Start of the requested UTC window (required, ISO 8601 format)
  • end_time: End of the requested UTC window (required, ISO 8601 format)

Power values are in MW, energy values in MWh. All times are UTC.

Path parameters

asset_idREQUIRED
stringThe ID of the asset

Query parameters

start_timeREQUIRED
string<date-time>Start time of the requested UTC window
end_timeREQUIRED
string<date-time>End time of the requested UTC window
Example value
curl "https://api.ebx.energy/v1/assets/DE_BESS_01/planned_state?start_time=2026-02-03T00:00:00Z&end_time=2026-02-04T00:00:00Z" \
  -H "Authorization: Bearer $EBX_TOKEN"
Example response200
{
  "asset_id": "<string>",
  "organization_id": "<string>",
  "start_time": "2026-09-10T13:30:00Z",
  "end_time": "2026-09-10T13:30:00Z",
  "scheduled_dispatch": [
    {
      "set_power": 0,
      "set_time": "2026-09-10T13:30:00Z"
    }
  ],
  "fcr_reservations": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "idempotency_key": "<string>",
      "start_time": "2026-09-10T13:30:00Z",
      "end_time": "2026-09-10T13:30:00Z",
      "offered_power": 0,
      "capacity_price": "<string>",
      "status": "PENDING"
    }
  ],
  "afrr_capacity_reservations": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "idempotency_key": "<string>",
      "start_time": "2026-09-10T13:30:00Z",
      "end_time": "2026-09-10T13:30:00Z",
      "product": "pos",
      "offered_power": 0,
      "energy_price": "<string>",
      "capacity_price": "<string>",
      "status": "PENDING"
    }
  ],
  "afrr_energy_reservations": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "idempotency_key": "<string>",
      "start_time": "2026-09-10T13:30:00Z",
      "end_time": "2026-09-10T13:30:00Z",
      "product": "pos",
      "offered_power": 0,
      "energy_price": "<string>",
      "status": "PENDING"
    }
  ],
  "power_limits": [
    {
      "start_time": "2026-09-10T13:30:00Z",
      "end_time": "2026-09-10T13:30:00Z",
      "upper_limit": 0,
      "lower_limit": 0,
      "reason": "maintenance",
      "reason_description": "<string>"
    }
  ],
  "energy_limits": [
    {
      "start_time": "2026-09-10T13:30:00Z",
      "end_time": "2026-09-10T13:30:00Z",
      "upper_limit": 0,
      "lower_limit": 0,
      "reason": "maintenance",
      "reason_description": "<string>"
    }
  ],
  "unavailabilities": [
    {
      "start_time": "2026-09-10T13:30:00Z",
      "end_time": "2026-09-10T13:30:00Z",
      "reason": "maintenance",
      "reason_description": "<string>"
    }
  ],
  "curtailments": [
    {
      "start_time": "2026-09-10T13:30:00Z",
      "end_time": "2025-01-02T18:00:00Z",
      "max_curtailment": 100,
      "min_curtailment": 0
    }
  ]
}
Can raise
  • 401no valid token
  • 403scope missing
  • 404unknown or not visible
  • 422validation failed
  • 429rate limited
ALL CODES →
GET/v1/assets/{asset_id}/state

Get State

asset.read

Get the latest state of a specific asset.

State is a collection of measurements that reflect the current internal operational status of the asset. Each field contains a list of exactly one measurement with a timestamp and a value.

Asset state includes various measurements. These are:

  • asset_status: Current asset availability as reported by the EMS — a discrete integer status code (the known codes are documented on the asset_status field schema). EBX forces this to 0 (not tradeable) when the asset has an active full unavailability, or a full power or full energy restriction, scheduled via the EBX API (even if the EMS reports it as available). Partial power/energy restrictions — and any other EMS code, known or unknown — are returned unchanged.
  • fcr_upper_limit (MW): Reserved FCR upper limit
  • fcr_lower_limit (MW): Reserved FCR lower limit
  • afrr_upper_limit (MW): Reserved aFRR upper limit
  • afrr_lower_limit (MW): Reserved aFRR lower limit
  • fcr_power_actual (MW): Actual FCR power output
  • afrr_power_actual (MW): Actual aFRR power output
  • fcr_power_setpoint (MW): Feedback of current FCR power setpoint
  • afrr_setpoint (MW): Feedback of current aFRR power setpoint
  • dispatch_setpoint (MW): Feedback of current intraday (BESS) dispatch setpoint.
  • dispatch15_setpoint (MW): Feedback of upcoming day-ahead 15-minute dispatch setpoint.
  • poc_setpoint (MW): Feedback of the current point-of-connection power setpoint.
  • control_mode: Feedback of the control scheme the EMS is applying, as the raw DPL integer code (the codes are documented on the control_mode field schema).
  • available_power_charge (MW): Available charge power indicates the current maximum power during charge that the battery can charge at a given moment.
  • available_power_discharge (MW): Available discharge power indicates the current maximum power during discharge (in MW) that the battery can discharge at a given moment.
  • soc_min (MWh): The minimum energy capacity defines the lower energy limit that the BESS can safely reach during discharge, typically set by the bottom of the allowable SoC window to avoid battery damage. It indicates the point below which no further energy can be delivered.
  • soc_max (MWh): The maximum energy capacity defines the upper energy limit that the BESS can store when fully charged, based on its design specifications and operational constraints (e.g., the top of the allowable SoC window). It represents the total usable energy available for discharge.
  • available_discharge_energy (MWh): Energy currently available for discharge (present energy level of the battery).
  • available_charge_energy (MWh): Energy currently available for charge (maximum energy the battery can still absorb).
  • available_soc_discharge / available_soc_charge (MWh): Deprecated aliases of the two fields above; same values.
  • poc_power_actual_ac (MW): The actual AC power at the grid point of connection at the current moment.
  • battery_power_actual_ac (MW): The actual AC power input/output of the battery at the current moment. For BESS-only assets this is also published as poc_power_actual_ac for backward compatibility; co-located assets report the two measurements independently.
  • battery_power_actual_dc (MW): The actual DC power input of the battery system at the current moment.
  • grid_switch_status (0/1): Indicates whether the asset is currently connected to or disconnected from the grid; 1 for connected, 0 for disconnected.
  • redispatch_active (0/1): Whether a TSO redispatch is currently active.
  • redispatch_amount (MW): Power amount of the active TSO redispatch.
  • self_consumption (MW): The amount of power consumed by the asset itself from its own generation.
  • frequency (Hz): The grid frequency at the asset's connection point.
  • is_fcr_on (0/1): A flag indicating whether FCR is currently active (1) or not (0).
  • is_afrr_on (0/1): A flag indicating whether aFRR is currently active (1) or not (0).
  • is_dispatch_on (0/1): A flag indicating whether wholesale dispatch is currently active (1) or not (0).
  • export_curtailment_dso (0-100%): Export curtailment by DSO; a percentage value (0-100%).
  • import_curtailment_dso (0-100%): Import curtailment by DSO; a percentage value (0-100%).
  • actual_battery_cycles (0-...): The number of cycles the battery has gone through since commissioning.
  • discharge_throughput (MWh): Total energy discharged by the battery since commissioning.
  • charge_throughput (MWh): Total energy charged by the battery since commissioning. PV (solar) measurements — populated only for assets with PV (i.e. pv_active=true):
  • pv_export_curtailment_dso (0-100%): Export curtailment applied by the DSO on the PV side.
  • pv_irradiance (W/m²): Solar irradiance at the PV array.
  • pv_power_dc_actual (MW): Actual DC power generated by the PV array at the current moment.
  • pv_inverter_self_consumption (MW): Power consumed by the PV inverter itself.
  • pv_switch_status (0/1): PV connection switch status; 1 for connected, 0 for disconnected.
  • pv_power_setpoint (MW): Feedback of the current PV power setpoint.

Virtual asset ids return the physical parent's state disaggregated by the active segmentation policy (MW/MWh measurements allocated, status passed through).

Path parameters

asset_idREQUIRED
string
Example value
curl "https://api.ebx.energy/v1/assets/DE_BESS_01/state" \
  -H "Authorization: Bearer $EBX_TOKEN"
Example response200
{
  "asset_status": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "operational_status": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "fcr_upper_limit": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "fcr_lower_limit": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "afrr_upper_limit": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "afrr_lower_limit": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "fcr_power_actual": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "afrr_power_actual": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "fcr_power_setpoint": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "afrr_setpoint": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "dispatch_setpoint": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "dispatch15_setpoint": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "dispatch_power_actual": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "available_power_charge": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "available_power_discharge": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "soc_min": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "soc_max": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "available_discharge_energy": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "available_charge_energy": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "available_soc_discharge": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "available_soc_charge": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "poc_power_actual_ac": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "battery_power_actual_ac": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "battery_power_actual_dc": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "grid_switch_status": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "self_consumption": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "frequency": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "is_fcr_on": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "is_afrr_on": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "is_dispatch_on": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "export_curtailment_dso": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "import_curtailment_dso": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "actual_battery_cycles": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "discharge_throughput": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "charge_throughput": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "pv_export_curtailment_dso": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "pv_irradiance": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "pv_power_dc_actual": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "pv_inverter_self_consumption": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "pv_switch_status": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "pv_power_setpoint": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "redispatch_active": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "redispatch_amount": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "poc_setpoint": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "control_mode": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "lte_signal_device_1": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "lte_signal_device_2": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "lan_connected_device_1": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "lan_connected_device_2": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ]
}
Can raise
  • 401no valid token
  • 403scope missing
  • 404unknown or not visible
  • 429rate limited
ALL CODES →
GET/v1/assets/{asset_id}/state/history

Get State History

asset.read

Get the historical state of a specific asset over a time range.

Returns time-series data for asset measurements between start_time and end_time. Each field in the response contains a list of measurements with timestamps and values.

Time window constraints:

  • Without downsampling (do_downsample=false): maximum 5-minute window
  • With downsampling (do_downsample=true): larger windows allowed, data aggregated to ~200 points per field
  • Data available up to 30 days in the past

Filtering by point names: Use point_names to request specific measurements only (e.g., frequency, soc_max). Both public API field names and internal field names are accepted. If not specified, all available measurements are returned.

See the /state endpoint documentation for the full list of available measurements. Virtual asset ids return the physical parent's history disaggregated by the active segmentation policy.

Path parameters

asset_idREQUIRED
string

Query parameters

start_timeREQUIRED
string<date-time>Start time for filtering results
end_timeREQUIRED
string<date-time>End time for filtering results
do_downsample
booleandefault falseWhether to downsample the raw data
point_names
array[string]Filter to specific point names (e.g., frequency, soc_max). Returns all if not specified.
Example value
curl "https://api.ebx.energy/v1/assets/DE_BESS_01/state/history?start_time=2026-02-03T00:00:00Z&end_time=2026-02-04T00:00:00Z" \
  -H "Authorization: Bearer $EBX_TOKEN"
Example response200
{
  "asset_status": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "operational_status": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "fcr_upper_limit": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "fcr_lower_limit": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "afrr_upper_limit": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "afrr_lower_limit": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "fcr_power_actual": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "afrr_power_actual": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "fcr_power_setpoint": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "afrr_setpoint": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "dispatch_setpoint": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "dispatch15_setpoint": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "dispatch_power_actual": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "available_power_charge": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "available_power_discharge": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "soc_min": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "soc_max": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "available_discharge_energy": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "available_charge_energy": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "available_soc_discharge": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "available_soc_charge": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "poc_power_actual_ac": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "battery_power_actual_ac": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "battery_power_actual_dc": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "grid_switch_status": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "self_consumption": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "frequency": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "is_fcr_on": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "is_afrr_on": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "is_dispatch_on": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "export_curtailment_dso": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "import_curtailment_dso": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "actual_battery_cycles": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "discharge_throughput": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "charge_throughput": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "pv_export_curtailment_dso": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "pv_irradiance": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "pv_power_dc_actual": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "pv_inverter_self_consumption": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "pv_switch_status": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "pv_power_setpoint": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "redispatch_active": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "redispatch_amount": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "poc_setpoint": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "control_mode": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "lte_signal_device_1": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "lte_signal_device_2": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "lan_connected_device_1": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ],
  "lan_connected_device_2": [
    {
      "timestamp": "2026-09-10T13:30:00Z",
      "value": 0
    }
  ]
}
Can raise
  • 401no valid token
  • 403scope missing
  • 404unknown or not visible
  • 422validation failed
  • 429rate limited
ALL CODES →

Send feedback

This goes straight to the docs team on Slack, with the page you are on. It is not attributed to you, so say who you are if you would like an answer.

0/2000