{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Understanding Charging Data","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"understanding-charging-data","__idx":0},"children":["Understanding Charging Data"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Concept"},"children":["Concept"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Resource"},"children":["Resource"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Question it answers"},"children":["Question it answers"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Charging session"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/charging_sessions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When was the vehicle physically plugged in?"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Charging sub-session"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/charging_sub_sessions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["How was charging being managed, and when did that change?"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Energy usage intervals"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/charging_sub_sessions/{id}/energy_usage"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["When was energy actually flowing, and how much?"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"charging-sessions-the-plug-in-episode","__idx":1},"children":["Charging sessions: the plug-in episode"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["charging session"]}," represents one physical plug-in episode. Its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start"]}," is when the vehicle was plugged in and its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end"]}," is when it was unplugged (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end"]}," is null while the vehicle is still plugged in). A session links to the one or more sub-sessions that occurred within it."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"charging-sub-sessions-how-charging-was-managed","__idx":2},"children":["Charging sub-sessions: how charging was managed"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["charging sub-session"]}," is a segment of a charging session during which a single charging mode (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SMART"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BOOST"]},", etc.) was active. A sub-session begins when the vehicle is plugged in ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["or"]}," when the mode changes, and ends when the vehicle is unplugged ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two things sub-session timestamps are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["They are not plug-in/plug-out times."]}," Only the first sub-session's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start"]}," and the last sub-session's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end"]}," coincide with those; use the parent charging session for the physical connection window."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["They are not the times energy was flowing."]}," A sub-session's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end"]}," bound the period the mode was ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["duration_minutes"]}," field reports how long energy was actually being delivered during the sub-session — it can be far shorter than the gap between ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end"]},", and it does not tell you ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["when"]}," within the window charging happened. For that, use energy usage intervals."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"energy-usage-intervals-when-power-actually-flowed","__idx":3},"children":["Energy usage intervals: when power actually flowed"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default the intervals are regular, fixed-length periods. Pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["energy_delivered_watt_hours__gt=0"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"worked-examples","__idx":4},"children":["Worked examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"mode-switch-during-one-plug-in-with-zero-charging-in-the-first-sub-session","__idx":5},"children":["Mode switch during one plug-in, with zero charging in the first sub-session"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Charging session: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start"]}," 22:00 → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end"]}," 06:30 (plugged in overnight, unplugged the next morning)",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sub-session 1 — mode ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SMART"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start"]}," 22:00 → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end"]}," 23:00, energy delivered: 0 Wh"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sub-session 2 — mode ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BOOST"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start"]}," 23:00 → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end"]}," 06:30, energy delivered: 20,000 Wh",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Energy usage (merged intervals): 23:00–01:30 delivering 20,000 Wh, then 01:30–06:30 at 0 Wh"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end"]}," overstate the charging window."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"one-sub-session-discontinuous-charging","__idx":6},"children":["One sub-session, discontinuous charging"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Charging session: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start"]}," 20:00 → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end"]}," 07:00",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sub-session 1 — mode ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SMART"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start"]}," 20:00 → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end"]}," 07:00 (no mode change, so this is the only sub-session)",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"which-timestamps-should-i-use","__idx":7},"children":["Which timestamps should I use?"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Plug-in / plug-out times"]}," → charging session ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When the user changed how charging was managed"]}," → sub-session ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mode"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When charging actually happened"]}," → energy usage intervals with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merge_consecutive_intervals=true"]}," (the intervals with non-zero energy delivered)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["How long charging actually happened for"]}," → sub-session ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["duration_minutes"]},", or sum the energy usage intervals with non-zero energy delivered."]}]}]},"headings":[{"value":"Understanding Charging Data","id":"understanding-charging-data","depth":1},{"value":"Charging sessions: the plug-in episode","id":"charging-sessions-the-plug-in-episode","depth":2},{"value":"Charging sub-sessions: how charging was managed","id":"charging-sub-sessions-how-charging-was-managed","depth":2},{"value":"Energy usage intervals: when power actually flowed","id":"energy-usage-intervals-when-power-actually-flowed","depth":2},{"value":"Worked examples","id":"worked-examples","depth":2},{"value":"Mode switch during one plug-in, with zero charging in the first sub-session","id":"mode-switch-during-one-plug-in-with-zero-charging-in-the-first-sub-session","depth":3},{"value":"One sub-session, discontinuous charging","id":"one-sub-session-discontinuous-charging","depth":3},{"value":"Which timestamps should I use?","id":"which-timestamps-should-i-use","depth":2}],"frontmatter":{"title":"Understanding charging data","seo":{"title":"Understanding Charging Data"}},"lastModified":"2026-07-13T10:52:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/understanding/charging_sessions","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}