> ## 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 vehicle state > Retrieve the current state of a vehicle device including battery level, range, charging status, and capacity ## OpenAPI ````yaml /openapi.json get /vehicle/{deviceId} 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: /vehicle/{deviceId}: get: tags: - Vehicle summary: Get vehicle state description: >- Retrieve the current state of a vehicle device including battery level, range, charging status, and capacity operationId: getVehicle parameters: - name: expedite required: false in: query description: Use expedite cache with 1 minute TTL instead of normal 15 minute TTL schema: example: false type: boolean - name: deviceId required: true in: path description: The unique identifier for the vehicle device schema: example: device_abc123 type: string responses: '200': description: Vehicle state 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/VehicleResponse' meta: $ref: '#/components/schemas/ResponseMeta' examples: vehicleCharging: summary: Vehicle plugged in and actively charging description: >- `plugged: true`, `charging: true`. `chargeRate` reflects live draw; `chargeTimeRemaining` projects time to the configured `chargeLimit`. value: success: true data: id: device_vehicle_001 vendor: example_vendor_a sync: available: true lastPulledAt: '2026-05-07T09:23:45.000Z' metadata: model: EV Sedan source: live state: batteryLevel: 64 range: 184 plugged: true charging: true fullyCharged: false batteryCapacity: 75 chargeLimit: 80 chargeRate: 7 chargeTimeRemaining: 110 maxCurrent: 32 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 vehicleFullyCharged: summary: Vehicle plugged in but fully charged description: >- `plugged: true`, `charging: false`, `fullyCharged: true`. Battery sits at the configured `chargeLimit`; the OEM has stopped drawing power. value: success: true data: id: device_vehicle_001 vendor: example_vendor_a sync: available: true lastPulledAt: '2026-05-07T07:00:00.000Z' metadata: model: EV Sedan source: live state: batteryLevel: 80 range: 232 plugged: true charging: false fullyCharged: true batteryCapacity: 75 chargeLimit: 80 chargeRate: 0 chargeTimeRemaining: 0 maxCurrent: 32 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 vehicleIdleParked: summary: Vehicle parked and unplugged description: >- Common at-home state: `plugged: false`, `charging: false`. No charging happening; the battery slowly self-discharges. value: success: true data: id: device_vehicle_001 vendor: example_vendor_a sync: available: true lastPulledAt: '2026-05-07T09:23:45.000Z' metadata: model: EV Sedan source: cache state: batteryLevel: 72 range: 209 plugged: false charging: false fullyCharged: false batteryCapacity: 75 chargeLimit: 80 chargeRate: 0 chargeTimeRemaining: 0 maxCurrent: 32 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 vehicleDriving: summary: Vehicle in motion (discharging) description: >- Negative `chargeRate` indicates the battery is being drawn from. `plugged: false`, `charging: false`. Range and battery level update as the vehicle moves. value: success: true data: id: device_vehicle_001 vendor: example_vendor_a sync: available: true lastPulledAt: '2026-05-07T09:23:45.000Z' metadata: model: EV Sedan source: live state: batteryLevel: 58 range: 168 plugged: false charging: false fullyCharged: false batteryCapacity: 75 chargeLimit: 80 chargeRate: -22.5 chargeTimeRemaining: 0 maxCurrent: 32 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 vehicleLowBattery: summary: Vehicle parked with low battery description: >- Battery below 20%. Useful for applications that surface charge-soon prompts or schedule cheap-rate top-ups. value: success: true data: id: device_vehicle_001 vendor: example_vendor_a sync: available: true lastPulledAt: '2026-05-07T09:23:45.000Z' metadata: model: EV Sedan source: cache state: batteryLevel: 12 range: 35 plugged: false charging: false fullyCharged: false batteryCapacity: 75 chargeLimit: 80 chargeRate: 0 chargeTimeRemaining: 0 maxCurrent: 32 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 vehicleOffline: summary: Vehicle unreachable description: >- `sync.available: false`. The OEM cloud has not heard from the vehicle for some time. The last successful pull is in `sync.lastPulledAt`; cached `state` may be stale. value: success: true data: id: device_vehicle_001 vendor: example_vendor_a sync: available: false lastPulledAt: '2026-05-06T22:14:10.000Z' metadata: model: EV Sedan source: fallback state: batteryLevel: 64 range: 184 plugged: false charging: false fullyCharged: false batteryCapacity: 75 chargeLimit: 80 chargeRate: 0 chargeTimeRemaining: 0 maxCurrent: 32 meta: requestId: req_8a2Bf3kP environment: sandbox timestamp: '2026-06-02T12:00:00.000Z' latencyMs: 12 '400': description: >- The device manufacturer rejected the pull request (`INVALID_PARAMETERS` or `COMMAND_FAILED`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '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: /vehicle/device_vehicle_001 latencyMs: 2 '403': description: >- Live access is disabled, consent is revoked, the device allowance is exceeded, or the manufacturer denied access to the device (`DEVICE_UNAUTHORIZED`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Device not found or access denied 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: /vehicle/device_unknown_999 latencyMs: 5 '410': description: >- The device is offline at the manufacturer. See the [device error codes](/reference/error-codes) reference for retry guidance. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: deviceOffline: summary: >- The manufacturer reports the device as offline. Use the cached state from the previous pull, or retry once the device is back online. value: success: false error: code: DEVICE_OFFLINE message: The device is currently offline at the manufacturer. meta: requestId: req_FnP7tAhH timestamp: '2026-04-29T12:00:00.000Z' path: /vehicle/device_vehicle_001 latencyMs: 142 '503': description: >- The device manufacturer service is temporarily unavailable. Retryable with exponential backoff. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: serviceUnavailable: summary: >- The manufacturer cloud is down or refusing requests. Retry with backoff. value: success: false error: code: SERVICE_UNAVAILABLE message: >- The device manufacturer service is temporarily unavailable. meta: requestId: req_GoQ8uBiI timestamp: '2026-04-29T12:00:00.000Z' path: /vehicle/device_vehicle_001 latencyMs: 1873 security: - api-key: [] x-codeSamples: - lang: curl label: curl source: |- curl --request GET \ --url 'https://api.amps.ai/vehicle/device_abc123' \ --header 'x-api-key: amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx' - lang: javascript label: Node source: >- const response = await fetch('https://api.amps.ai/vehicle/device_abc123', { 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/vehicle/device_abc123' headers = { 'x-api-key': 'amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx', } response = requests.get(url, headers=headers) data = response.json() components: schemas: VehicleResponse: type: object properties: id: type: string description: Unique identifier for the vehicle device. vendor: type: string description: OEM display name (e.g. `tesla`, `rivian`). sync: type: object properties: available: type: boolean lastPulledAt: anyOf: - type: string - type: 'null' required: - available - lastPulledAt metadata: type: object properties: model: type: string cacheType: type: string enum: - expedite - normal source: type: string enum: - cache - live - fallback - projection description: >- How this device-state reading was obtained. `live`: read from the device just now. `cache`: a recent reading served from cache. `fallback`: the most recent stored reading, returned when the device could not be reached. `projection`: simulated sandbox state — sandbox devices are not physical hardware, so their reported state reflects the commands you have sent. degraded: description: >- Present and `true` when this reading was served from stored state because the platform is temporarily not contacting this device’s manufacturer (a protective circuit is open). The data is the most recent known reading, not a live one. Absent on a normal reading. type: boolean required: - model - source state: type: object properties: batteryLevel: type: number minimum: 0 maximum: 100 description: Current battery level as a percentage (0–100). range: type: number minimum: 0 description: Estimated remaining driving range in miles. plugged: type: boolean description: Whether the vehicle is currently plugged in to a charger. charging: type: boolean description: Whether the vehicle is actively drawing charge right now. fullyCharged: type: boolean description: Whether the battery has reached its configured charge limit. batteryCapacity: type: number minimum: 0 description: Total usable battery capacity in kWh. chargeLimit: type: number minimum: 0 maximum: 100 description: Configured charge limit as a percentage (0–100). chargeRate: type: number description: Current charge rate in kW. Negative when discharging. chargeTimeRemaining: type: number minimum: 0 description: Estimated time remaining to reach the charge limit, in minutes. maxCurrent: type: number minimum: 0 description: Maximum charging current the vehicle will accept, in amperes. required: - batteryLevel - range - plugged - charging - fullyCharged - batteryCapacity - chargeLimit - chargeRate - chargeTimeRemaining - maxCurrent required: - id - vendor - sync - metadata - state title: Vehicle Response 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 ````