Charger management

Overview statistics

Available: tenant fleet API. One read-only route gives a dashboard home its figures: charging sessions, energy, session success rate and average duration over a period, the stations that delivered the most energy, how many stations are online, offline or faulted now, and billed revenue.

GET /v1/tenants/{tenant_id}/stats?from=&to=&bucket=day&time_zone=UTC&top=5

It needs stations:read. The revenue fields also need billing:read; without it they are null and everything else is returned. Read-only viewers can use it. Another tenant's statistics answer 403.

Period and buckets

Parameter	Default	Meaning
`from`	`to` minus 24 hours (hour), 30 days (day) or 365 days (month)	ISO 8601 date-time; without an offset it is UTC
`to`	Now	ISO 8601 date-time, exclusive
`bucket`	`day`	`hour`, `day` or `month`
`time_zone`	`UTC`	IANA name, for example `America/Los_Angeles`. Day and month buckets start at local midnight, so a daylight saving day has 23 or 25 hours
`top`	`5`	How many top stations to return, 1 to 20

The period is widened to whole buckets: from is rounded down and to up to a bucket boundary. The response states the result as start and end, in the requested time zone. A series holds at most 168 hour, 92 day or 24 month buckets, and a period at most 50,000 sessions. A larger request answers 422 stats_range_too_large; ask for a shorter period or a larger bucket.

A session counts in the bucket in which it started, with its whole energy.

Response

{"tenant_id":7,"bucket":"day","time_zone":"UTC",
 "start":"2026-10-01T00:00:00+00:00","end":"2026-10-03T00:00:00+00:00",
 "sessions_as_of":"2026-10-14T09:00:00.123456+00:00",
 "totals":{"sessions":5,"active_sessions":1,"ended_sessions":4,"successful_sessions":1,
   "success_rate":"0.2500","average_duration_seconds":4125,
   "energy_kwh":"28.941","energy_wh":28941,"energy_unknown_sessions":1},
 "series":[{"start":"2026-10-01T00:00:00+00:00","end":"2026-10-02T00:00:00+00:00",
   "sessions":2,"ended_sessions":2,"successful_sessions":1,"success_rate":"0.5000",
   "average_duration_seconds":2850,"energy_kwh":"6.941","energy_wh":6941,
   "revenue":[{"currency":"USD","billed_minor":243,"bills":1}]}],
 "top_stations":[{"station_id":13,"name":"acme2-01","sessions":3,"energy_kwh":"22","energy_wh":22000}],
 "stations":{"as_of":"2026-10-14T09:00:00.123456+00:00","total":4,"online":2,"offline":1,"faulted":1},
 "revenue":{"basis":"final_bills","currencies":[{"currency":"USD","billed_minor":943,"bills":2}]}}

Field	Meaning
`sessions`	Transactions that started in the period or bucket, active ones included
`ended_sessions`	Of those, the ones that have ended
`successful_sessions`	Ended sessions that delivered at least 1 Wh and did not stop for a fault, emergency stop, reset, reboot, power loss, power quality, timeout or deauthorization
`success_rate`	`successful_sessions / ended_sessions` as decimal text with 4 places; `null` when none ended
`average_duration_seconds`	Mean whole seconds from start to end of the ended sessions; `null` when none ended
`energy_unknown_sessions`	Sessions without an energy total, or with a negative or implausible one (above 1,000 kWh); their energy is not summed
`top_stations`	Stations by energy over the period, most first; `name` is `null` for a station deleted since
`stations`	State now, not for the period. `offline`: not connected. `faulted`: connected, with a connector whose last status is `Faulted`. `online`: connected, with no faulted connector

Units

Field	Unit	Source
`energy_kwh`	kWh, decimal text	The core's transaction totals (kWh), summed exactly
`energy_wh`	Wh, integer	The same total
`average_duration_seconds`	Seconds	Transaction start and end
`billed_minor`	Minor units of `currency`	Final bills' `total_minor`

Revenue

Revenue comes only from this API's bills: the final bills of the period, counted by when they were finalized, summed per currency. It is billed revenue. Captures, releases and refunds are the payment provider's records and are not subtracted. Figures of the legacy payment service and the core's revenue view are never included.

Freshness

Session figures are cached for 60 seconds (hour buckets), 5 minutes (day) or 15 minutes (month); sessions_as_of says when they were read. Station state is cached for 30 seconds (stations.as_of). Revenue is read on every request. A dashboard should poll no more often than the cache period of its bucket.

Agents

The MCP tool get_overview_stats calls this route with the key's tenant and needs stations:read.