Anatomy of a session

Copy linkBlocks

Discrete windows of active charging within a session. Use blocks to render a visual timeline of when the vehicle was (or will be) charging and when it was idle.

While UPCOMING, blocks are empty. While ACTIVE, blocks represent a mix of past charging and planned future charging — past blocks are final, future blocks are tentative and may shift as the schedule re-optimizes. While SETTLED, blocks are final and represent what actually happened.

Each block has a type (BATTERY_RESERVE, REGULAR, or IMMEDIATE_START), a kwhSum tracking the total energy delivered during that block, and time boundaries (startAt, endAt).

Copy linkStatistics

Charging data for the session. Use statistics to show how much energy was delivered, the battery level progression, and a charge rate chart.

aggregated provides session-level totals (total kWh, battery start/end percentages). It is null while UPCOMING and populated once ACTIVE.

timeseries is an array of 15-minute interval measurements spanning from plug-in to plug-out. During gaps between blocks, kwh is 0. Use this to render a charge rate graph — the zeros make idle periods and block boundaries visible.

Copy linkTarget

What the system is charging towards. Use the target to display the user's charging goal — the battery level they want and when they need it by.

target.latest is a discriminated union on type:

• A REGULAR target has a deadline (readyBy), a charge target (minimumChargeTarget), a battery reserve floor, and a source indicating whether it comes from the policy or a user override.
• An IMMEDIATE_START target has only a minimumChargeTarget — no deadline, no flexibility.

The target can change mid-session (e.g. the user triggers an immediate start override). latest always reflects the current state. When an override completes, the system reverts to the regular schedule target.

Copy linkOutcome

The system's assessment of whether the target will be (or was) met. Use the outcome to show the user whether they're on track — and if not, what the system expects will happen.

outcome.latest is null before the first estimate is available (always null while UPCOMING). Once ACTIVE, it matches the target type — use type to distinguish REGULAR from IMMEDIATE_START outcomes:

• A REGULAR outcome is a discriminated union on state: an ON_TARGET outcome has batteryLevelAtReadyBy and minimumChargeTargetReachedAt set to null (the target will be met, so projections are unnecessary); an OFF_TARGET outcome populates batteryLevelAtReadyBy with the estimated battery level at the deadline, and minimumChargeTargetReachedAt with the projected time the target will eventually be reached (or null if a projection is unavailable, for example if charging has failed to start).
• An IMMEDIATE_START outcome tracks when the target will be reached via minimumChargeTargetReachedAt (null when a projection is unavailable).

outcome.latest.targetId links back to the specific target being evaluated, so you can correlate the two.

Copy linkError

Whether something has gone wrong with charge control. Use the error to surface actionable alerts to the user.

error.latest is null when there is no active error. Use type to identify the error kind: START_FAIL (charging failed to start), STOP_FAIL (charging failed to stop), or MISSING_CAPABILITIES (the vehicle is missing capabilities required for session management, such as charge state reporting or charge control — the missingCapabilities array lists exactly which ones). Errors resolve automatically — when the issue clears, error.latest returns to null.