Skip to content

Charging Sessions

Endpoints related to records of charging. See Understanding charging data for how charging sessions (plug-in episodes), charging sub-sessions (per-mode segments) and energy usage intervals (actual energy delivery) relate to each other.

Schemas
Operations

List charging sessions

Request

List all charging sessions visible to the authenticated client. Each session represents one physical plug-in episode: its start/end are the plug-in and unplug times. A session contains one or more charging sub-sessions — one per contiguous period in a single charging mode.

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

See Understanding charging data for how charging sessions, sub-sessions and energy usage intervals relate.

Security
oauth2(Required scopes: charging_session:read)
Query
page_beforestring[a-z]{4}[A-Z\d]{26}

Return results from the page after this ID.

Example:page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR
page_afterstring[a-z]{4}[A-Z\d]{26}

Return results from the page before this ID.

Example:page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR
page_sizeinteger, [ 1 .. 100 ]

Specify the number of results to return per page.

Default:25
Example:page_size=10
expandArray of strings

Specify a url field to expand into a nested resource.

Items Enum:"vehicle""evse""sub_sessions"
Headers
EvEnergy-Versionnumber

Specify the version of this endpoint to use.

Value:2
EvEnergy-Userstringuser[A-Z\d]{26}

If the client is authenticated using Client Credentials, setting EvEnergy-User to a valid user ID allows requests to be made as if you were directly authenticated as that user.

Example:user01HN2NJ9NMRZBXT1H6FT9N7735
curl -i -X GET \
  'https://developers.ev.energy/_mock/ev.energy-api-v2/charging_sessions?page_before=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_after=xmpl01HNFZM7Q8FXASZXYZ6XM3TQRR&page_size=10&expand=vehicle' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'EvEnergy-User: user01HN2NJ9NMRZBXT1H6FT9N7735' \
  -H 'EvEnergy-Version: 2'

Responses

Returns a list of charging sessions, sorted newest first.

Headers
EvEnergy-Versionnumber

Indicates the version of the API that generated this response. If EvEnergy-Version was not specified in the request, this will be your OAuth application's default version.

Value:2
X-RateLimit-Limitnumber

The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

Default:1000
X-RateLimit-Remainingnumber

The number of requests remaining until this client's rate limit is reached.

Default:999
RetryAfternumber

The number of seconds until this client's requests will not be rate limited.

Default:3600
Bodyapplication/json
Array [
idstringcses[A-Z\d]{26}read-onlyrequired

Unique identifier for the charging session.

Example:"cses01HSH04KDEWF6Z4DB2J77J74K5"
urlstring, (uri)required
Example:"https://api.ev.energy/v2/charging_sessions/cses01HSH04KDEWF6Z4DB2J77J74K5"
startstring, (date-time)read-onlyrequired

When the plug-in episode began, i.e. when the vehicle was plugged in.

endstring or null, (date-time)read-only

When the plug-in episode ended, i.e. when the vehicle was unplugged. Null while the vehicle is still plugged in.

vehicle(string or null) or Vehicle (object)
One of:
string or null (uri)
evse(string or null) or EVSE (object)
One of:
string or null (uri)
sub_sessionsArray of strings or Array of objects
One of:

Links to sub-sessions by default.

Array of strings (uri)
]
Response
[
  {
    "id": "cses01HSH04KDEWF6Z4DB2J77J74K5",
    "url": "https://api.ev.energy/v2/charging_sessions/cses01HSH04KDEWF6Z4DB2J77J74K5",
    "start": "2019-08-24T14:15:22Z",
    "end": "2019-08-24T14:15:22Z",
    "vehicle": "https://api.ev.energy/v2/vehicles/vhcl01HRFF3SEVSCRAV9B3CHVDFN0H",
    "evse": "https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5",
    "sub_sessions": [ … ]
  }
]