Read session history - Amps AI Documentation

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

curl https://api.amps.ai/ev-charger/device_abc123 \
  -H "x-api-key: $AMPS_API_KEY"

{
  "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

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

{
  "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.

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

Start and stop a session

Charge now, pause, or charge inside a time window.

Pull

Read shape, freshness, and pagination.