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

# Read session history

> List an EV charger's past charging sessions and the energy each one delivered.

A charging session is one plug-in to unplug. List a charger's sessions, newest first, to show last night's charge or reconcile energy over a month.

## 1. Check the device keeps history

```bash theme={null}
curl https://api.amps.ai/ev-charger/device_abc123 \
  -H "x-api-key: $AMPS_API_KEY"
```

```json theme={null}
{
  "success": true,
  "data": {
    "id": "device_abc123",
    "sessions": true
  }
}
```

`sessions: false` means the manufacturer records no history. Asking anyway returns `422 DEVICE_NOT_CAPABLE`, every time, so read the flag instead of retrying.

## 2. List sessions

```bash theme={null}
curl "https://api.amps.ai/ev-charger/device_abc123/sessions?limit=2" \
  -H "x-api-key: $AMPS_API_KEY"
```

```json theme={null}
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "evs_Ht6vB1zQnE5wXpKm7ArJdU",
        "status": "active",
        "startedAt": "2026-07-29T22:48:00.000Z",
        "energyDelivered": { "value": 12.3, "unit": "kwh" },
        "measurement": "metered"
      },
      {
        "id": "evs_9tQ2mK4xPvR8sLdN3bWfYc",
        "status": "completed",
        "startedAt": "2026-07-28T22:31:00.000Z",
        "endedAt": "2026-07-29T04:12:00.000Z",
        "energyDelivered": { "value": 41.6, "unit": "kwh" },
        "measurement": "metered",
        "endReason": "vehicle_finished"
      }
    ],
    "pagination": { "limit": 2, "offset": 0, "total": 3, "hasMore": true },
    "window": { "from": "2026-06-30T09:15:00.000Z", "to": "2026-07-30T09:15:00.000Z" }
  }
}
```

An `active` session has no `endedAt` or `endReason`, and its `energyDelivered` is a running total. Times are UTC, and `id` is stable, so you can store it as a key.

| Field | |
| - | - |
| `measurement` | How `energyDelivered` was measured: `metered` (the charger's energy register), `oem_reported` (the manufacturer's total), or `inferred` (estimated from power readings). None is a billing-grade guarantee. |
| `endReason` | `unplugged`, `vehicle_finished`, `stopped`, `power_lost`, `fault`, or `unknown`. Absent when the charger gives no reason. |

## 3. Filter and page

| Parameter | |
| - | - |
| `from`, `to` | ISO 8601 UTC. Returns sessions that overlap the window. `to` defaults to now, `from` to 30 days before `to`. Up to 400 days. |
| `status` | `active` or `completed`. |
| `limit`, `offset` | `limit` is 1 to 50, default 10. |

Pin the window when you page: send the first page's `window.to` as `to` on every later request, so a session that starts mid-walk doesn't shift rows past you.

```bash theme={null}
curl "https://api.amps.ai/ev-charger/device_abc123/sessions?limit=50&offset=50&to=2026-07-30T09:15:00.000Z" \
  -H "x-api-key: $AMPS_API_KEY"
```

Stop when `pagination.hasMore` is `false`. For energy in the session that's running now, `state.sessionEnergy` on the device read is the live figure.

## Next steps

<CardGroup cols={2}>
  <Card title="Start and stop a session" icon="plug" href="/cookbooks/ev-charger/start-stop-session">
    Charge now, pause, or charge inside a time window.
  </Card>

  <Card title="Pull" icon="arrow-down" href="/guides/pull">
    Read shape, freshness, and pagination.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.