System state
const url = 'https://demo.evcc.io/api/state?jq=.';const options = {method: 'GET'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://demo.evcc.io/api/state?jq=.'Returns the complete state of the system. This structure is used by the UI and also published via websocket and MQTT. It can be filtered by JQ to only return a subset of the data. Note: the response mirrors the internal UI state and carries no compatibility promise. Fields may change or disappear between releases.
Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Filter the state with JQ
Examples
complete state
.only first loadpoint
.loadpoints[0]Responses
Section titled “Responses”Success
Complete system state as returned by /api/state and pushed via websocket and MQTT. This structure mirrors the internal UI state and carries no compatibility promise. Fields may change or disappear between releases.
object
Telemetry is enabled.
Experimental UI features are enabled.
Initial setup is required.
Startup has completed.
HTTP API is ready to accept requests.
Charging locations. One entry per configured loadpoint.
A charging location with a charger, an optional dedicated meter and an optional vehicle.
object
Unique loadpoint identifier used in API routes and configuration.
Battery boost is active. When enabled, home battery power is used for fast charging.
Charging current per phase in A.
Duration of the current charging session in seconds.
Current charging power in W.
Estimated remaining charging time in seconds.
Estimated remaining energy in kWh.
Total energy imported by the charge meter in kWh.
Charging voltage per phase in V.
Energy charged in the current charging session in kWh.
The connected vehicle is not identified automatically by its status.
Values are averaged.
Values are cached.
The climater state of the connected vehicle is ignored for charge control.
Charger only supports full ampere steps for current control.
Charger is a heating device where disabled means normal operation.
Charger is a heating device. SoC values represent temperature in degrees.
Charger is an always-connected device without vehicles and charging sessions, like a heat pump.
The connected vehicle only provides data while charging.
Vehicle API calls are retried on failure.
The connected vehicle pushes data updates instead of being polled.
Charger is a switchable device without current control, like a heat pump or switch socket.
No wake-up calls are sent to the connected vehicle.
The connected vehicle may need a short welcome charge to start communicating.
Charger icon name for UI display.
Charger supports automatic switching between 1-phase and 3-phase charging.
Charger is physically connected with a single phase.
Reason why the charger is waiting, like a pending authorization or a required disconnect.
A vehicle is connected and charging.
A vehicle is connected to the charger.
Duration since the vehicle was connected, in seconds.
Delay before charging stops in solar mode, in seconds.
Grid draw power above which charging stops in solar mode, in W.
Currently applied SoC limit in %.
Currently applied maximum charging current in A.
Currently applied minimum charging current in A.
Currently applied minimum SoC in %.
Id of the currently applied charging plan. Zero if no plan is active.
SoC goal in % of the currently applied charging plan.
Target time of the currently applied charging plan.
Currently applied charging plan strategy.
object
Force continuous charging without gaps.
Duration of uninterrupted charging directly before the target time, in seconds.
Currently applied priority.
Delay before charging starts in solar mode, in seconds.
Available surplus power above which charging starts in solar mode, in W.
Charger is currently allowed to charge.
Session energy limit in kWh. Zero means no limit.
Session SoC limit in %. Zero means no limit.
Maximum charging current in A.
Minimum charging current in A.
Minimum SoC in %. Vehicle is fast-charged until this level is reached.
Vehicle SoC is below the configured minimum SoC.
Charging behavior.
Current offered to the vehicle in A.
Pending phase switching action in solar mode.
Remaining time until the pending phase switching action executes, in seconds.
Number of phases expected to be used for charging.
Configured phase mode. 0 is automatic switching, 1 and 3 select a fixed phase count.
Time slots of the current charging plan.
A time slot with an associated price or emission value.
object
Start of the time slot.
End of the time slot.
Price per kWh in the configured currency or emissions in g/kWh.
The current time slot is an active charging slot of the plan.
Energy goal of the charging plan in kWh.
Duration in seconds the charging plan is projected to miss its target time.
Charging plan strategy.
object
Force continuous charging without gaps.
Duration of uninterrupted charging directly before the target time, in seconds.
Projected end of the charging plan. End of the last planned slot.
Projected start of the charging plan. Start of the earliest planned slot.
Target time of the charging plan.
Priority for surplus distribution. Higher number means higher priority.
Pending charge start or stop action in solar mode.
Remaining time until the pending charge start or stop action executes, in seconds.
Energy used in the last 24 hours in kWh.
Energy used in the last 7 days in kWh.
Average CO₂ emissions of the current charging session in g/kWh.
Energy charged in the current charging session in kWh.
Total cost of the current charging session in the configured currency.
Average energy price of the current charging session per kWh in the configured currency.
Share of solar energy in the current charging session in %.
Fast charging with cheap or clean grid energy is currently active.
Price or emission limit for fast charging with grid energy.
Start of the next fast charging period with cheap or clean grid energy.
Charging pause for prioritized feed-in is currently active.
Feed-in rate limit above which charging is paused.
Start of the next charging pause for prioritized feed-in.
Charging suggestion from the battery optimizer.
object
Suggested charging action.
Recommended charge power in W.
Recommended discharge power in W.
Suggestion differs from the current operating mode.
Loadpoint title for UI display.
Energy used since midnight in kWh.
Climater of the connected vehicle is active.
Automatic vehicle detection is running.
SoC limit configured in the vehicle itself, in %.
Unique name of the connected vehicle. Empty for guest vehicles.
Odometer reading of the connected vehicle in km.
Range of the connected vehicle in km.
Charge level of the connected vehicle in %. Temperature in degrees for heating devices.
Title of the connected vehicle for UI display.
A short welcome charge is active to enable vehicle communication.
SoC limit for battery boost in %.
Display-only UI settings.
object
Lower bound of the temperature scale for heating devices, in degrees.
Upper bound of the temperature scale for heating devices, in degrees.
Price, CO₂ and solar production forecasts.
object
Grid price forecast. Price per kWh in the configured currency per time slot.
CO₂ emission forecast in g/kWh per time slot.
Solar production forecast.
object
Correction factor applied to the forecast based on past production.
Expected production today.
object
Expected production energy in kWh.
Forecast data covers the whole day.
Expected production tomorrow.
object
Expected production energy in kWh.
Forecast data covers the whole day.
Expected production the day after tomorrow.
object
Expected production energy in kWh.
Forecast data covers the whole day.
Expected production power over time.
Charging cost forecast used by the plan optimizer per time slot.
Feed-in rate forecast. Rate per kWh in the configured currency per time slot.
Temperature forecast in °C per time slot.
Configured currency for all monetary values.
Fatal startup errors.
A fatal startup error.
object
Error message.
Device class the error originates from, like meter or charger.
Name of the device that caused the error.
Status of configured vehicle authentication providers, keyed by provider name.
object
object
Running evcc version.
Latest available evcc version.
Operating system and architecture.
Server time zone abbreviation and UTC offset.
Aggregated home battery state.
object
Current battery power in W. Positive means discharging, negative means charging.
Total battery capacity in kWh.
Charge level in %. Weighted by capacity across all batteries.
Total battery energy in kWh.
Measurement data per battery meter.
Measurement data of a single home battery meter.
object
Unique device name of the meter.
Current power in W.
Meter title for UI display.
Meter icon name for UI display.
Total energy in kWh.
Total exported energy in kWh.
Power per phase in W.
Current per phase in A.
Charge level in %.
Battery supports external control of its operation mode.
Battery capacity in kWh. Zero when not specified.
Battery optimizer suggestion.
object
Suggested operation mode.
Recommended charge power in W.
Recommended discharge power in W.
Suggestion differs from the current operating mode.
Projected charge levels based on the solar and price forecast.
object
Projected highest charge level.
object
Projected charge level in %.
Time of the projected charge level.
The projection hits the upper or lower battery limit.
Projected lowest charge level.
object
Projected charge level in %.
Time of the projected charge level.
The projection hits the upper or lower battery limit.
Current operation mode of the home battery.
Grid meter data.
object
Unique device name of the meter.
Current power in W.
Meter title for UI display.
Meter icon name for UI display.
Total energy in kWh.
Total exported energy in kWh.
Power per phase in W.
Current per phase in A.
A grid meter is configured.
Solar generation meters. One entry per configured pv meter.
Measurement data of a single meter.
object
Unique device name of the meter.
Current power in W.
Meter title for UI display.
Meter icon name for UI display.
Total energy in kWh.
Total exported energy in kWh.
Power per phase in W.
Current per phase in A.
Total solar generation power in W. Sum of all pv meters.
Total solar generation energy in kWh.
Auxiliary consumption meters. Their power is treated as available for charging.
Measurement data of a single meter.
object
Unique device name of the meter.
Current power in W.
Meter title for UI display.
Meter icon name for UI display.
Total energy in kWh.
Total exported energy in kWh.
Power per phase in W.
Current per phase in A.
Total power of all auxiliary meters in W.
Additional meters for monitoring purposes.
Measurement data of a single meter.
object
Unique device name of the meter.
Current power in W.
Meter title for UI display.
Meter icon name for UI display.
Total energy in kWh.
Total exported energy in kWh.
Power per phase in W.
Current per phase in A.
Consumption meters of individual devices for monitoring purposes.
Measurement data of a single meter.
object
Unique device name of the meter.
Current power in W.
Meter title for UI display.
Meter icon name for UI display.
Total energy in kWh.
Total exported energy in kWh.
Power per phase in W.
Current per phase in A.
Home consumption power in W.
Configured grid operating point in W. Positive values maintain grid import.
Share of green energy in home consumption, between 0 and 1.
Share of green energy used for charging, between 0 and 1.
Configured tariffs. Structure depends on configuration.
object
Static configuration.
Runtime status.
Source of the configuration, evcc.yaml file or database.
Current grid energy price per kWh in the configured currency.
Current feed-in rate per kWh in the configured currency.
Current grid CO₂ emissions in g/kWh.
Current cost of solar generation per kWh in the configured currency.
Current energy price of home consumption per kWh, taking the green energy share into account.
Current energy price of charging per kWh, taking the green energy share into account.
Current CO₂ emissions of home consumption in g/kWh, taking the green energy share into account.
Current CO₂ emissions of charging in g/kWh, taking the green energy share into account.
Current outside temperature in °C.
MQTT integration configuration.
object
Broker address.
Root topic all values are published under.
Broker username.
Broker password. Redacted.
MQTT client id.
Skip TLS certificate verification.
CA certificate for TLS connections.
Client certificate for TLS connections.
Client key for TLS connections.
InfluxDB integration configuration.
object
InfluxDB server URL.
Database name (InfluxDB 1.x) or bucket (InfluxDB 2.x).
Organization (InfluxDB 2.x).
Access token (InfluxDB 2.x). Redacted.
Username (InfluxDB 1.x).
Password (InfluxDB 1.x). Redacted.
Skip TLS certificate verification.
Network configuration.
object
URL schema, http or https.
Hostname.
HTTP port.
Externally reachable URL.
URL in the local network.
Home energy management system integration.
object
Static configuration.
object
A home energy management system is configured.
Runtime status.
object
Consumption is currently limited.
Allowed feed-in in %. Values below 100 mean production is curtailed.
Maximum allowed consumption power in W.
Maximum allowed production power in W.
Source of the configuration, evcc.yaml file or database.
SMA Home Manager configuration.
object
SMA vendor id.
SMA device id.
SMA device serial.
Sponsorship status.
object
Static configuration.
Runtime status.
object
Name of the sponsor.
Expiry time of the sponsor token.
Sponsor token expires soon.
Sponsor token. Redacted.
Source of the configuration, evcc.yaml file or database.
EEBus integration configuration and status.
object
Static configuration.
object
URI the EEBus service listens on.
Port the EEBus service listens on.
SHIP id.
Network interfaces the EEBus service uses.
TLS certificate.
object
Public certificate in PEM format.
Private key in PEM format. Redacted.
Runtime status.
object
SKI (subject key identifier) used for pairing.
QR code payload for pairing.
Source of the configuration, evcc.yaml file or database.
Remote access configuration and connection status.
object
Static configuration.
object
Remote access is enabled.
Runtime status.
object
Connection to the remote access server is established.
Remote access URL.
Remote login attempts are currently blocked by the rate limiter.
Last remote activity per client, keyed by username. RFC3339 timestamps.
object
Last connection error.
Source of the configuration, evcc.yaml file or database.
Modbus proxy configuration.
A Modbus proxy forwarding requests to a physical device.
object
Port the proxy listens on.
How write requests are handled.
Connection settings of the physical device.
object
Device address for TCP connections.
Use RTU protocol over TCP.
Serial device path.
Serial baud rate.
Serial communication parameters.
Messaging services configuration. Structure depends on configuration.
object
Static configuration.
Runtime status.
Source of the configuration, evcc.yaml file or database.
Configured notification messages per event type.
object
A configured notification message.
object
Message title template.
Message body template.
Notifications for this event are disabled.
A configured notification message.
object
Message title template.
Message body template.
Notifications for this event are disabled.
A configured notification message.
object
Message title template.
Message body template.
Notifications for this event are disabled.
A configured notification message.
object
Message title template.
Message body template.
Notifications for this event are disabled.
A configured notification message.
object
Message title template.
Message body template.
Notifications for this event are disabled.
A configured notification message.
object
Message title template.
Message body template.
Notifications for this event are disabled.
A configured notification message.
object
Message title template.
Message body template.
Notifications for this event are disabled.
A configured notification message.
object
Message title template.
Message body template.
Notifications for this event are disabled.
A configured notification message.
object
Message title template.
Message body template.
Notifications for this event are disabled.
Update interval of the control loop in seconds.
Load management circuits, keyed by circuit name.
object
A load management circuit limiting power and current of its assigned loadpoints.
object
Circuit title for UI display.
Circuit icon name for UI display.
Name of the parent circuit.
Current power in W.
Current in A.
Maximum allowed power in W.
Maximum allowed current in A.
Battery buffer SoC in %. Energy above this level may be used for charging in solar mode.
Battery priority SoC in %. Home battery is charged first while below this level.
Battery buffer start SoC in %. Solar charging starts automatically above this level.
Home battery discharge is prevented during fast charging and planned charging.
Home battery is allowed to discharge to the grid (experimental).
Solar forecast is adjusted to real production data (experimental).
Price or emission limit for charging the home battery from grid.
Home battery is currently charged from grid.
A dynamic grid price or CO₂ forecast is configured.
Type of the smart charging limit, price based or emission based.
A feed-in tariff with forecast is configured.
Time of the last energy history update.
Configured site title.
Colors assigned to devices for consistent UI display.
Color assigned to a device for consistent UI display.
object
Device title the color is assigned to.
Assigned color as CSS value.
Configured vehicles, keyed by vehicle name.
object
A configured vehicle.
object
Unique vehicle name used in API routes and configuration.
Minimum SoC in %. Vehicle is fast-charged until this level is reached.
SoC limit in %. Charging stops when reached.
Repeating charging plans.
A repeating charging plan.
object
Weekdays the plan is active. 0 is Sunday, 6 is Saturday.
Target time in HH:MM format.
Time zone of the target time, like Europe/Berlin.
SoC goal in %.
Plan is active.
Charging plan strategy.
object
Force continuous charging without gaps.
Duration of uninterrupted charging directly before the target time, in seconds.
Vehicle title for UI display.
Feature flags of the vehicle implementation.
Usable battery capacity in kWh.
Vehicle icon name for UI display.
Charging statistics over different time periods.
object
Aggregated charging statistics for a time period.
object
Average CO₂ emissions in g/kWh.
Average energy price per kWh in the configured currency.
Total charged energy in kWh.
Share of solar energy in %.
Aggregated charging statistics for a time period.
object
Average CO₂ emissions in g/kWh.
Average energy price per kWh in the configured currency.
Total charged energy in kWh.
Share of solar energy in %.
Aggregated charging statistics for a time period.
object
Average CO₂ emissions in g/kWh.
Average energy price per kWh in the configured currency.
Total charged energy in kWh.
Share of solar energy in %.
Aggregated charging statistics for a time period.
object
Average CO₂ emissions in g/kWh.
Average energy price per kWh in the configured currency.
Total charged energy in kWh.
Share of solar energy in %.
Authentication is disabled.
Path of the evcc configuration file.
Path of the evcc database.
OCPP server configuration and connected stations.
object
OCPP server configuration.
object
Port the OCPP server listens on.
OCPP server status.
object
Externally reachable URL of the OCPP server.
Connection status per configured station.
Connection status of an OCPP station.
object
Station id.
Connection status.
OCPP forwarder rules and upstream connection status.
object
Static configuration.
A rule forwarding an OCPP station to an upstream backend.
object
Station id to forward.
URL of the upstream OCPP backend.
Password for upstream authentication. Redacted.
Station id used towards the upstream backend.
Username for upstream authentication.
Skip TLS certificate verification.
CA certificate for TLS connections.
Only forward read operations to the station.
Runtime status.
Connection status of an OCPP forwarder rule.
object
Charger id.
URL of the upstream OCPP backend.
Connection to the upstream backend is established.
Last connection error.
Source of the configuration, evcc.yaml file or database.
Battery optimizer is enabled.
Selected battery optimizer charging strategy.
Available battery optimizer charging strategies.
Built-in MCP server is enabled.
Instance runs in demo mode.
Example
{ "loadpoints": [ { "chargerStatusReason": "unknown", "mode": "off", "phaseAction": "inactive", "pvAction": "inactive", "suggestion": { "action": "charge" } } ], "currency": "AUD", "system": "linux/amd64", "timezone": "CEST +02:00", "battery": { "devices": [ { "suggestion": { "action": "normal" } } ] }, "batteryMode": "unknown", "tariffs": { "yamlSource": "file" }, "hems": { "yamlSource": "file" }, "sponsor": { "yamlSource": "file" }, "eebus": { "yamlSource": "file" }, "remote": { "yamlSource": "file" }, "modbusproxy": [ { "readonly": "false", "settings": { "baudrate": 1200, "comset": "8N1" } } ], "messaging": { "yamlSource": "file" }, "smartCostType": "co2", "vehicles": { "additionalProperty": { "mode": "off" } }, "ocpp": { "status": { "stations": [ { "status": "unknown" } ] } }, "ocppforwarder": { "yamlSource": "file" }}