> ## Documentation Index
> Fetch the complete documentation index at: https://docs.der-connect.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Charge Sessions API

> See when and where a vehicle charged and how much energy it consumed.

A Charge Session captures a complete charging event for an electric vehicle or charge point. Detailing when charging started, when it ended, how much energy was used, and where it happened.

While the Readings API gives you snapshots of a vehicle’s state over time, the Charge Sessions API gives you a summarized view of each session. This is useful for building timelines, estimating charging costs, or tracking behavior over time.

## How sessions are calculated

Depending on the Entity type and hardware manufacturer, sessions are either calculated based on the vehicle’s Readings (most common), or measured directly by the hardware manufacturer.

Calculated sessions are based on either power flow or changes in state of charge. We automatically select the best method based on the data available for each vehicle. However, the calculation method doesn’t affect how sessions appear to you. All sessions are normalized and reliable for most common use cases.

We calculate each Entity's Charge Sessions once per day. Ongoing sessions won't show up until they are completed.

## Activate the feature to get started

Before you can use this API, you'll have to enable the `CaptureChargeSessions` [Feature](/api-reference/endpoint/entity-settings/features) on an Entity of type `EV` or `CP`. We'll show you how to do that in this guide.

When you enable this feature, we'll check if the Entity is compatible. In some cases, we may require the vehicle’s [Battery Capacity](/api-reference/endpoint/entity-settings/battery-capacity) to be set before the feature can be activated. In rare cases, the feature may not be available due to limitations from the hardware manufacturer.

## What you'll need

* A valid access (bearer) token
* An Entity of type `EV` or `CP`

## Let's try it out

<Steps>
  <Step title="Set the vehicle's battery capacity (optional)">
    You may need to set the vehicle's [Battery Capacity](/api-reference/endpoint/entity-settings/battery-capacity/update-the-battery-capacity-of-an-entity) before sessions can be captured.

    If you’re unsure whether this applies to your vehicle, or if you are working with a charge point instead, you can skip this step and try enabling the feature directly. If the Battery Capacity is required, the request will return an error asking you to provide it.

    You'll need to specify the <Tooltip tip="The ID of the Entity.">entityId</Tooltip> and <Tooltip tip="The ID of the Entity.">batteryCapacity</Tooltip> in kWh.
  </Step>

  <Step title="Start capturing charge sessions">
    You'll have to enable an [Entity Feature](/api-reference/endpoint/entity-settings/features) to start capturing Charge Sessions.

    [Activate the feature for your Entity](/api-reference/endpoint/entity-settings/features/activate-or-deactivate-an-entity-feature), identified by its <Tooltip tip="The ID of the Entity.">entityId</Tooltip>, setting <Tooltip tip="Available options: CaptureChargeSessions">feature</Tooltip> to `CaptureChargeSessions` and <Tooltip tip="Available options: CaptureChargeSessions">enabled</Tooltip> to `true`.

    ```json Request (Body) theme={null}
    {
      "feature": "CaptureChargeSessions",
      "enabled": true
    }
    ```
  </Step>

  <Step title="List Charge Sessions">
    <Icon color="rgb(var(--primary))" icon="mug-hot" iconType="solid" />  <span className="font-semibold" style={{color: 'rgb(var(--primary))'}}>It might be time for a break.</span>\
    <span class="text-sm"> A Charge Session may take up to 24 hours to appear after the vehicle has finished charging.</span>

    Once you're ready, use the <Tooltip tip="The ID of the Entity.">entityId</Tooltip> to [List all Charge Sessions](/api-reference/endpoint/charge-sessions-api/list-charging-records-1) for it.

    You'll also have to specify a <Tooltip tip="The start of the time frame (UTC).">start</Tooltip> date. Sessions that started before this time won't be part of the response.

    <ParamField body="start" type="string" required />

    ```json Response (Body) [expandable] theme={null}
    {
      "data": [
        {
          "id": "3c90c3cc-[...]-8dd25736052a",
          "entityId": "7ac991f9-[...]-1577b91625b5",
          "created": "2024-06-10T01:31:56Z",
          "data": {
            "start": "2024-06-09T14:35:21.384Z",
            "end": "2024-06-09T15:15:25.685Z",
            "charge": {
              "total": {
                  "total": 49.2450,
                  "unit": "kWh"
              },
              "averagePower": {
                  "unit": "kW",
                  "value": 85.7777
              },
              "start": {
                  "unit": "%",
                  "value": 23
              },
              "end": {
                  "unit": "%",
                  "value": 90
              },
            },
            "range": {
              "start": {
                  "unit": "km",
                  "value": 104.3498
              },
              "end": {
                  "unit": "km",
                  "value": 405.3132
              }
            },
            "locationMatches": [
              {
                "accuracy": 0.9,
                "location": {
                  "id": "0db9516e-[...]-41de6cb46af4", 
                  "label": "Home"
                }
              }
            ]
          }
        }
      ], ...
    }
    ```

    <Warning>
      <span className="font-semibold">Caution</span>\
      The <Tooltip tip="The charge location in latitude and longitude coordinates.">location</Tooltip> object might not be available to you. However, our [Location Matching](/guides/location-matching) feature is a privacy-friendly alternative available to all users.
    </Warning>
  </Step>
</Steps>

## Good to know

* Charge Sessions are generated once every day, as long as the feature is enabled.
* In most cases, Charge Sessions won’t be generated retroactively.
* Unfinished Charge Sessions won't show up.
* Exact locations are usually hidden to protect privacy. If your use case requires exact locations, reach out to our team. In most cases, we recommend using Location Matching — a privacy-friendly alternative.
* Information about a vehicle's range or state of charge is only available when connected to a vehicle directly.