> ## 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. # Get EV Charger charging sessions > **Session history depends on the charger.** Read `sessions` on `GET /ev-charger/{deviceId}` first: `false` means the manufacturer records none and this endpoint answers 422 `SESSIONS_NOT_SUPPORTED`. Returns this charger's charging sessions, newest first. A session is one plug-in-to-completion episode; `measurement` states how `energyDelivered` was arrived at, so a caller billing against the figure can tell a metered reading from an integrated estimate. No `measurement` value is a settlement-grade guarantee. Paged with the usual `limit`/`offset`. ## OpenAPI ````yaml /openapi.json get /ev-charger/{deviceId}/sessions openapi: 3.1.0 info: title: Amps.ai API description: >- Energy device management API for batteries, EV chargers, solar inverters, and HVAC systems version: '1.0' contact: {} servers: - url: https://api.amps.ai description: Amps API security: [] tags: [] paths: /ev-charger/{deviceId}/sessions: get: tags: - EV Charger summary: Get EV Charger charging sessions description: >- **Session history depends on the charger.** Read `sessions` on `GET /ev-charger/{deviceId}` first: `false` means the manufacturer records none and this endpoint answers 422 `SESSIONS_NOT_SUPPORTED`. Returns this charger's charging sessions, newest first. A session is one plug-in-to-completion episode; `measurement` states how `energyDelivered` was arrived at, so a caller billing against the figure can tell a metered reading from an integrated estimate. No `measurement` value is a settlement-grade guarantee. Paged with the usual `limit`/`offset`. operationId: listEvChargerSessions parameters: - name: offset required: false in: query schema: type: integer minimum: 0 default: 0 description: 'Number of sessions to skip (default: 0).' - name: limit required: false in: query schema: type: integer minimum: 1 maximum: 50 default: 10 description: 'Maximum number of sessions to return (1-50, default: 10).' - name: status required: false in: query description: >- Filter to sessions still running (`active`) or finished (`completed`). schema: enum: - active - completed type: string - name: to required: false in: query description: >- Only report sessions overlapping up to this instant (ISO 8601 UTC). Defaults to now. schema: example: '2026-07-30T00:00:00.000Z' type: string - name: from required: false in: query description: >- Only report sessions overlapping this instant onwards (ISO 8601 UTC). Defaults to 30 days before `to`. schema: example: '2026-07-01T00:00:00.000Z' type: string - name: deviceId required: true in: path description: The unique identifier for the EV Charger device. schema: example: device_abc123 type: string responses: '200': description: Charging sessions retrieved successfully. content: application/json: schema: type: object required: - success - data - meta properties: success: type: boolean const: true description: Always `true` for success responses. data: $ref: '#/components/schemas/EvChargerSessionList' meta: $ref: '#/components/schemas/ResponseMeta' examples: firstPage: summary: First page, with a session still running description: >- Newest first. The running session has no `endedAt` and no `endReason`; its `energyDelivered` is what has been delivered so far. `hasMore` is true, so raise `offset` by `limit` for the next page — and send `window.to` back as `to`, so a session starting mid-walk cannot push a row past you. value: success: true data: items: - id: evs_Ht6vB1zQnE5wXpKm7ArJdU deviceId: device_abc123 status: active startedAt: '2026-07-29T22:48:00.000Z' energyDelivered: value: 12.3 unit: kwh measurement: metered links: device: /ev-charger/device_abc123 - id: evs_9tQ2mK4xPvR8sLdN3bWfYc deviceId: device_abc123 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 links: device: /ev-charger/device_abc123 pagination: limit: 2 offset: 0 total: 3 hasMore: true window: from: '2026-06-29T09:15:00.000Z' to: '2026-07-29T09:15:00.000Z' meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 lastPage: summary: Last page description: >- Requested with `to` set to the `window.to` the first page returned, so both pages were cut from the same set. `hasMore` is false, so the walk is finished. value: success: true data: items: - id: evs_9tQ2mK4xPvR8sLdN3bWfYc deviceId: device_abc123 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 links: device: /ev-charger/device_abc123 pagination: limit: 2 offset: 2 total: 3 hasMore: false window: from: '2026-06-29T09:15:00.000Z' to: '2026-07-29T09:15:00.000Z' meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 noSessions: summary: No sessions in the window description: >- The charger reports session history but nothing overlaps the requested window. `window` states the window that was searched; widen `from`/`to` to look further back. value: success: true data: items: [] pagination: limit: 10 offset: 0 total: 0 hasMore: false window: from: '2026-06-29T09:15:00.000Z' to: '2026-07-29T09:15:00.000Z' meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 '400': description: >- Invalid query parameters (e.g. a `from`/`to` that is not an ISO 8601 instant, a window longer than 400 days, or `limit` outside 1-50). Every code at this status: `COMMAND_FAILED`, `INVALID_PARAMETERS`, `UNSUPPORTED_CREDENTIAL_TYPE`, `VALIDATION_ERROR`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: windowTooLong: summary: >- The requested window is longer than the platform will report over value: success: false error: code: VALIDATION_ERROR message: Request validation failed. details: description: >- The reporting window cannot exceed 400 days. Narrow `from`/`to` and request the remainder separately. meta: requestId: req_2fJ7kPqV timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_abc123/sessions latencyMs: 4 badWindow: summary: '`from` is not an ISO 8601 instant' value: success: false error: code: VALIDATION_ERROR message: Request validation failed. details: fields: from: - Invalid ISO datetime description: Invalid query parameters meta: requestId: req_2fJ7kPqV timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_abc123/sessions latencyMs: 4 '401': description: Invalid or missing API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingApiKey: summary: No `x-api-key` header present value: success: false error: code: UNAUTHORIZED message: Authentication is required. details: description: API key is required meta: requestId: req_8sW2dRtX timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_abc123/sessions latencyMs: 2 '403': description: >- Error codes: `FORBIDDEN`, `INVALID_MFA_CODE`, `MFA_REQUIRED`, `ACCOUNT_LOCKED`, `DEVICE_UNAUTHORIZED`, `CONSENT_REVOKED`, `DEVICE_OVERAGE`, `LIVE_ACCESS_DISABLED`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- Device not found or access denied. Every code at this status: `CREDENTIAL_NOT_FOUND`, `DEVICE_NOT_FOUND`, `NO_DEVICES_FOUND`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: deviceNotFound: summary: No device matches the ID for this customer value: success: false error: code: DEVICE_NOT_FOUND message: No matching device was found for the supplied details. details: description: Device not found or access denied meta: requestId: req_5pH1cQbY timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_unknown_999 latencyMs: 5 '409': description: 'Error codes: `VEHICLE_NOT_CONNECTED`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '410': description: 'Error codes: `DEVICE_OFFLINE`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '413': description: 'Error codes: `PAYLOAD_TOO_LARGE`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '415': description: 'Error codes: `UNSUPPORTED_MEDIA_TYPE`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- This charger reports no session history (`SESSIONS_NOT_SUPPORTED`): its manufacturer records none that Amps can read. Permanent, so no retry changes it — `sessions` on the device read says the same thing before you spend a request. Amps refuses rather than returning an empty page that would claim no sessions happened. Every code at this status: `COMMAND_NOT_SUPPORTED`, `SESSIONS_NOT_SUPPORTED`, `SETTING_OUT_OF_RANGE`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: sessionsNotSupported: summary: >- This charger records no session history, and no retry changes it value: success: false error: code: SESSIONS_NOT_SUPPORTED message: >- The device manufacturer does not report charging session history. meta: requestId: req_7kL3nRtZ timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_abc123/sessions latencyMs: 3 '429': description: 'Error codes: `RATE_LIMITED`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: 'Error codes: `INTERNAL_ERROR`, `UNKNOWN_ERROR`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '502': description: 'Error codes: `NETWORK_ERROR`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- The manufacturer service is temporarily down (`SERVICE_UNAVAILABLE`). Nothing was read; retry with exponential backoff. Every code at this status: `SERVICE_UNAVAILABLE`, `SIMULATED_FAILURE`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: serviceUnavailable: summary: >- The manufacturer, or the read itself, is temporarily down — retry value: success: false error: code: SERVICE_UNAVAILABLE message: >- The device manufacturer service is temporarily unavailable. meta: requestId: req_9pQ2mWxB timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_abc123/sessions latencyMs: 812 '504': description: >- The manufacturer did not answer in time (`TIMEOUT`). Nothing was read; retry. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: timeout: summary: The manufacturer did not answer in time — retry value: success: false error: code: TIMEOUT message: The device manufacturer did not respond in time. meta: requestId: req_4tH8vKnD timestamp: '2026-04-29T12:00:00.000Z' path: /ev-charger/device_abc123/sessions latencyMs: 30000 security: - api-key: [] x-codeSamples: - lang: curl label: curl source: |- curl --request GET \ --url 'https://api.amps.ai/ev-charger/device_abc123/sessions' \ --header 'x-api-key: amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx' - lang: javascript label: Node source: >- const response = await fetch('https://api.amps.ai/ev-charger/device_abc123/sessions', { method: 'GET', headers: { 'x-api-key': 'amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx', }, }); const data = await response.json(); - lang: python label: Python source: |- import requests url = 'https://api.amps.ai/ev-charger/device_abc123/sessions' headers = { 'x-api-key': 'amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx', } response = requests.get(url, headers=headers) data = response.json() components: schemas: EvChargerSessionList: type: object properties: items: type: array items: oneOf: - type: object properties: id: type: string description: >- Amps identifier for this charging session. Opaque and unique across every charger, so it can be used as a key. It is not the manufacturer’s own session number. deviceId: type: string description: The charger the session took place on. startedAt: type: string format: date-time description: UTC instant the vehicle was plugged in. status: type: string const: active description: The vehicle is still plugged in. energyDelivered: description: >- Energy delivered so far. Absent when the charger reports no running total. type: object properties: value: type: number minimum: 0 description: Energy delivered, in kilowatt-hours. Never negative. unit: type: string const: kwh description: >- Always `kwh`. A session total is measured in nothing else. required: - value - unit measurement: description: >- How the `energyDelivered` figure was arrived at. `metered` — read from a cumulative energy register on the charger. `oem_reported` — the manufacturer computed the session total itself. `inferred` — derived by integrating power readings across the session, so its accuracy is bounded by how often the charger was sampled. None of the three is a settlement-grade guarantee: `metered` says the charger kept the count, not that the charger is a certified revenue meter or that the reading has been reconciled. Treat the value as provenance, and take the accuracy you need for billing from the charger’s own metering certification. Absent with it. type: string enum: - metered - oem_reported - inferred links: type: object properties: device: type: string description: >- Canonical path to the charger this session took place on: `GET /ev-charger/{deviceId}`. required: - device description: Hypermedia links for this session. required: - id - deviceId - startedAt - status - links - type: object properties: id: type: string description: >- Amps identifier for this charging session. Opaque and unique across every charger, so it can be used as a key. It is not the manufacturer’s own session number. deviceId: type: string description: The charger the session took place on. startedAt: type: string format: date-time description: UTC instant the vehicle was plugged in. status: type: string const: completed description: The session has finished. endedAt: type: string format: date-time description: UTC instant the session ended. energyDelivered: type: object properties: value: type: number minimum: 0 description: Energy delivered, in kilowatt-hours. Never negative. unit: type: string const: kwh description: >- Always `kwh`. A session total is measured in nothing else. required: - value - unit description: Total energy delivered over the session. measurement: type: string enum: - metered - oem_reported - inferred description: >- How the `energyDelivered` figure was arrived at. `metered` — read from a cumulative energy register on the charger. `oem_reported` — the manufacturer computed the session total itself. `inferred` — derived by integrating power readings across the session, so its accuracy is bounded by how often the charger was sampled. None of the three is a settlement-grade guarantee: `metered` says the charger kept the count, not that the charger is a certified revenue meter or that the reading has been reconciled. Treat the value as provenance, and take the accuracy you need for billing from the charger’s own metering certification. endReason: description: Why the session ended, when the charger says. type: string enum: - unplugged - vehicle_finished - stopped - power_lost - fault - unknown links: type: object properties: device: type: string description: >- Canonical path to the charger this session took place on: `GET /ev-charger/{deviceId}`. required: - device description: Hypermedia links for this session. required: - id - deviceId - startedAt - status - endedAt - energyDelivered - measurement - links pagination: type: object properties: limit: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Maximum number of items returned. offset: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Number of items skipped. total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Total number of items matching the query. hasMore: type: boolean description: '`true` if more items exist beyond the current page.' required: - limit - offset - total - hasMore window: type: object properties: from: type: string format: date-time description: Start of the window this page was reported over. to: type: string format: date-time description: End of the window this page was reported over. required: - from - to description: >- The reporting window this page was cut from, as the request resolved it. Echo `to` back as the `to` query parameter on every subsequent page: the list is newest-first and grows at the head, so pinning the upper bound is what keeps a session that starts mid-paging from displacing a row you have not read yet. required: - items - pagination - window title: EV Charging Sessions description: >- A page of charging sessions, newest first. A session is one plug-in-to-completion episode; `measurement` states the provenance of `energyDelivered`, so a caller can tell a metered reading from an integrated estimate. Provenance is not accuracy: no `measurement` value promises a settlement-grade figure. ResponseMeta: type: object title: Response Meta description: >- Metadata attached to every response: the request identifier, the serving environment, the build timestamp, and the server-side latency. required: - environment - timestamp - latencyMs properties: requestId: description: >- Unique request identifier. Echoes the `x-request-id` header when present; otherwise generated server-side. type: string environment: type: string description: The environment that served the request (`sandbox` or `live`). timestamp: type: string format: date-time description: ISO 8601 timestamp when the response was built. latencyMs: type: integer description: Server-side processing time in milliseconds. ErrorResponse: type: object properties: success: type: boolean description: Always `false` for error responses. error: type: object properties: code: type: string enum: - INVALID_CREDENTIALS - INVALID_API_KEY - INVALID_MFA_CODE - MFA_REQUIRED - ACCOUNT_LOCKED - UNSUPPORTED_CREDENTIAL_TYPE - DEVICE_NOT_FOUND - DEVICE_OFFLINE - DEVICE_UNAUTHORIZED - NO_DEVICES_FOUND - COMMAND_FAILED - COMMAND_NOT_SUPPORTED - EXECUTION_NOT_SUPPORTED - MODE_OVERRIDDEN - VPP_LOCKED - INVALID_PARAMETERS - INVALID_OEM_PARAMETERS - INVALID_TIME_WINDOW - BIND_NOT_SUPPORTED - SCHEDULER_ACTIVE - SCHEDULER_FULL - UNSUPPORTED_AUTH_PATH - SETTING_OUT_OF_RANGE - NETWORK_ERROR - RATE_LIMITED - SERVICE_UNAVAILABLE - TIMEOUT - NOT_YET_AVAILABLE - SIMULATED_FAILURE - UNKNOWN_ERROR - VEHICLE_NOT_CONNECTED - SESSIONS_NOT_SUPPORTED - CREDENTIAL_NOT_FOUND - OEM_CIRCUIT_OPEN - INVALID_OEM_RESPONSE - COMMAND_NOT_APPLIED - STALE_ACTION - DEFERRED_SCHEDULE_FAILED - UNROUTABLE_ACTION_TYPE - UNAUTHORIZED - EXPIRED_TOKEN - FORBIDDEN - INSUFFICIENT_PERMISSIONS - LIVE_ACCESS_DISABLED - VALIDATION_ERROR - INVALID_INPUT - INVALID_REQUEST_BODY - EMPTY_SETTINGS - PAYLOAD_TOO_LARGE - UNSUPPORTED_MEDIA_TYPE - NOT_FOUND - METHOD_NOT_ALLOWED - CONFLICT - CONFLICT_IN_EXECUTION - GONE - RATE_LIMIT_EXCEEDED - INTERNAL_ERROR - NOT_IMPLEMENTED - BAD_GATEWAY - GATEWAY_TIMEOUT - DEVICE_TYPE_MISMATCH - CONSENT_REVOKED - DEVICE_OVERAGE - SETTINGS_STORE_UNAVAILABLE - ACTION_NOT_FOUND - DIRECT_ACTION_UNSUPPORTED - UNSUPPORTED_ACTION - UNSUPPORTED_MODE - UNSUPPORTED_PARAMETER - UNSUPPORTED_PARAMETER_COMBINATION - UNSUPPORTED_UNIT - PARAMETER_OUT_OF_RANGE - START_IN_PAST - START_OUT_OF_RANGE - START_OFFSET_NOT_ACCEPTED - START_INVALID_FORMAT - START_NONEXISTENT_WALL_CLOCK - TIMEZONE_UNRESOLVED - INVALID_TIMEZONE - ACTION_NOT_CANCELLABLE - STRATEGY_NOT_SUPPORTED - UNSUPPORTED_SETTING - UNSUPPORTED_SETTING_COMBINATION - READ_ONLY_SETTING - INVALID_SETTING_UNIT - INVALID_SETTING_VALUE - NO_OP - NO_OVERRIDE - AVAILABILITY_ENV_UNSUPPORTED - UNSUPPORTED_COMBINATION description: >- Machine-readable error code (e.g. `VALIDATION_ERROR`, `CONFLICT`, `UNSUPPORTED_MODE`). Stable across releases; safe to switch on. message: type: string description: Human-readable error message. details: description: >- Structured context for the error: which fields were invalid, which actions conflicted, which capabilities the device declares. Shape varies by error code. type: object properties: {} additionalProperties: {} required: - code - message description: Error envelope. meta: type: object properties: requestId: description: >- Unique request identifier. Echoes the `x-request-id` header when present; otherwise generated server-side. type: string timestamp: type: string description: ISO 8601 timestamp when the error response was built. path: type: string description: Request path that produced the error. latencyMs: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Server-side processing time in milliseconds. required: - timestamp - path - latencyMs description: Request metadata. required: - success - error - meta title: Error Response description: >- Uniform error response. The `error.code` identifies the failure, `error.message` carries a human-readable explanation, and `error.details` carries structured context (failed fields, conflicting action IDs, supported capabilities) where relevant. securitySchemes: api-key: type: apiKey in: header name: x-api-key ````