Anatomy of a session

Copy linkBlocks

Discrete windows within a session. Use blocks to render a visual timeline of when the vehicle was or will be charging and when the system intended charging to pause.

While UPCOMING, blocks are empty. While ACTIVE, blocks represent a mix of past and planned future activity — 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 mode (CHARGING or RESTRICTION). Charging blocks have a type of BATTERY_RESERVE, REGULAR, or IMMEDIATE_START. Restriction blocks have type: "RESTRICTION" and normally carry no energy, although kwhSum may be positive when charging continued despite the requested pause. All blocks include startAt, endAt, and kwhSum.

The source field records whether the target governing the block came from the policy or a user override. Existing blocks retain their original source when a target changes. Use this to attribute energy in billing and reporting flows.

Blocks also report flexibility as FULL, LIMITED, or NONE, describing whether the block could move by at least one hour, less than one hour, or not at all when planned.

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.

Copy linkRestrictions

Whether charging is currently restricted by a user-initiated pause request. Use restrictions to show end users that charging has been requested to pause and when normal scheduling will resume.

restrictions.current is null when no restriction is active. An active restriction includes type (currently FULL), source (USER_OVERRIDE), startsAt, and endsAt. While it is active, blocks include RESTRICTION-mode windows and charging is planned around the restriction.

Creating a restriction while an immediate-start override is active cancels the immediate start. Setting a new IMMEDIATE_START target cancels an active restriction.