Understanding Charging Data

Charging activity is exposed through three related concepts, each answering a different question. Confusing them is the most common source of misread data, so read this page before building on the charging endpoints.

A charging session represents one physical plug-in episode. Its start is when the vehicle was plugged in and its end is when it was unplugged (end is null while the vehicle is still plugged in). A session links to the one or more sub-sessions that occurred within it.

Charging sessions are recorded from the feature's release (July 2026) onwards. Earlier charging history has not been backfilled and is available only as charging sub-sessions.

A charging sub-session is a segment of a charging session during which a single charging mode (SMART, BOOST, etc.) was active. A sub-session begins when the vehicle is plugged in or when the mode changes, and ends when the vehicle is unplugged or the mode changes again. A single plug-in episode contains exactly one sub-session if the mode never changed, and several if it did — for example, pressing Boost in the app ends the current smart sub-session and starts a boost sub-session, without the vehicle ever being unplugged.

Two things sub-session timestamps are not:

• They are not plug-in/plug-out times. Only the first sub-session's start and the last sub-session's end coincide with those; use the parent charging session for the physical connection window.
• They are not the times energy was flowing. A sub-session's start/end bound the period the mode was active. Within that window, energy delivery may begin late (smart charging waiting for a cheap or low-carbon period), finish early (the target charge level was reached), or occur in several separate bursts.

The duration_minutes field reports how long energy was actually being delivered during the sub-session — it can be far shorter than the gap between start and end, and it does not tell you when within the window charging happened. For that, use energy usage intervals.

The /charging_sub_sessions/{id}/energy_usage endpoint returns the actual energy delivery for a sub-session as a list of intervals, each reporting a start time, a length, and the energy delivered.

By default the intervals are regular, fixed-length periods. Pass merge_consecutive_intervals=true to merge consecutive intervals of energy delivery (and consecutive intervals of no delivery) into combined periods of irregular length: the response then alternates between actual charging windows and 0 Wh gap intervals. To keep only the charging windows, also filter with energy_delivered_watt_hours__gt=0.

• Charging session: start 22:00 → end 06:30 (plugged in overnight, unplugged the next morning)
  • Sub-session 1 — mode SMART, start 22:00 → end 23:00, energy delivered: 0 Wh
  • Sub-session 2 — mode BOOST, start 23:00 → end 06:30, energy delivered: 20,000 Wh
    • Energy usage (merged intervals): 23:00–01:30 delivering 20,000 Wh, then 01:30–06:30 at 0 Wh

The vehicle is plugged in at 22:00 with smart charging enabled. The scheduler is waiting for a cheap overnight rate, so the smart sub-session delivers nothing. At 23:00 the user presses Boost: that ends the smart sub-session and starts a boost sub-session, but the vehicle was never unplugged — the parent session runs underneath both. Boost finishes charging by 01:30 (battery target reached), well before the 06:30 unplug, so even the boost sub-session's own start/end overstate the charging window.

• Charging session: start 20:00 → end 07:00
  • Sub-session 1 — mode SMART, start 20:00 → end 07:00 (no mode change, so this is the only sub-session)
    • Energy usage (merged intervals): 0 Wh until 00:00, charging 00:00–02:00, 0 Wh 02:00–05:00, charging 05:00–06:00, 0 Wh until 07:00

The vehicle is plugged in for 11 hours with no mode change, so there is a single 11-hour sub-session — but the scheduler only delivered power from 00:00–02:00 (off-peak charging) and 05:00–06:00 (pre-departure top-up), about 3 hours of actual charging.

• Plug-in / plug-out times → charging session start/end.
• When the user changed how charging was managed → sub-session start/end and mode.
• When charging actually happened → energy usage intervals with merge_consecutive_intervals=true (the intervals with non-zero energy delivered).
• How long charging actually happened for → sub-session duration_minutes, or sum the energy usage intervals with non-zero energy delivered.