# 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.

| Concept | Resource | Question it answers |
|  --- | --- | --- |
| Charging session | `/charging_sessions` | When was the vehicle physically plugged in? |
| Charging sub-session | `/charging_sub_sessions` | How was charging being managed, and when did that change? |
| Energy usage intervals | `/charging_sub_sessions/{id}/energy_usage` | When was energy actually flowing, and how much? |


## Charging sessions: the plug-in episode

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.


## Charging sub-sessions: how charging was managed

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.

## Energy usage intervals: when power actually flowed

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`.

## Worked examples

### Mode switch during one plug-in, with zero charging in the first sub-session

- 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.

### One sub-session, discontinuous charging

- 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.

## Which timestamps should I use?

- **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.