Skip to main content
GET
/
battery
/
{deviceId}
curl
curl --request GET \
  --url 'https://api.amps.ai/battery/dev_abc123' \
  --header 'x-api-key: amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx'
{
  "id": "device_abc123",
  "vendor": "example_vendor_a",
  "sync": {
    "available": true,
    "lastPulledAt": "2026-05-07T09:23:45.000Z"
  },
  "metadata": {
    "model": "Hybrid 5kWh",
    "source": "cache",
    "cacheType": "normal"
  },
  "state": {
    "status": "idle",
    "capacity": 10.4,
    "level": 67,
    "chargeRate": 0,
    "dischargeLimit": 10,
    "currentMode": "auto.balanced"
  },
  "commands": {
    "charge": {
      "type": "set_operation_mode",
      "parameters": {
        "target": {
          "unit": "percent",
          "min": 10,
          "max": 100
        },
        "power": {
          "unit": "kw",
          "min": 0,
          "max": 5
        },
        "reserve": {
          "unit": "percent",
          "min": 0,
          "max": 100
        }
      },
      "execution": [
        "immediate",
        "scheduled",
        "windowed"
      ]
    },
    "discharge": {
      "type": "set_operation_mode",
      "parameters": {
        "target": {
          "unit": "percent",
          "min": 10,
          "max": 100
        },
        "power": {
          "unit": "kw",
          "min": 0,
          "max": 5
        },
        "reserve": {
          "unit": "percent",
          "min": 0,
          "max": 100
        }
      },
      "execution": [
        "immediate",
        "scheduled",
        "windowed"
      ]
    },
    "idle": {
      "type": "set_operation_mode",
      "parameters": {},
      "execution": [
        "immediate",
        "scheduled"
      ]
    },
    "auto.balanced": {
      "type": "set_operation_mode",
      "parameters": {},
      "execution": [
        "immediate",
        "scheduled"
      ]
    },
    "auto.reserve": {
      "type": "set_operation_mode",
      "parameters": {},
      "execution": [
        "immediate",
        "scheduled"
      ]
    },
    "auto.export": {
      "type": "set_operation_mode",
      "parameters": {},
      "execution": [
        "immediate",
        "scheduled"
      ]
    }
  },
  "settings": {
    "safety_reserve": {
      "value": 10,
      "unit": "percent",
      "min": 0,
      "max": 100
    },
    "discharge_floor": {
      "value": 20,
      "unit": "percent",
      "min": 0,
      "max": 100
    },
    "charge_ceiling": {
      "value": 100,
      "unit": "percent",
      "min": 0,
      "max": 100
    },
    "export_limit": {
      "value": 5000,
      "unit": "watts",
      "min": 0
    },
    "max_charge_rate": {
      "value": 25,
      "unit": "amps",
      "min": 0
    },
    "max_discharge_rate": {
      "value": 25,
      "unit": "amps",
      "min": 0
    },
    "scheduler_enabled": {
      "value": false
    }
  }
}

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.

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
deviceId
string
required

The unique identifier for the battery device.

Example:

"device_abc123"

Query Parameters

​
expedite
boolean

Bypass the standard 15-minute cache and serve a result no older than 1 minute. Use sparingly; cache misses incur a live OEM round-trip.

Example:

false

Response

Battery state retrieved successfully.

Carries live state (status, level, capacity, charge/discharge rates), connection metadata and sync info, the device's writable settings, and the per-canonical-command commands map. The schema enumerates every canonical command, parameter, and setting because the response shape is uniform across OEMs, but capabilities are presence-based: a real device only exposes the subset its OEM declares. A field is present if the device supports it, absent if it does not.

​
id
string
required
​
vendor
string
required
​
sync
object
required
​
metadata
object
required
​
state
object
required
​
commands
object

Per-canonical-command capability and the per-device source of truth for orchestration. Use it to validate or build push bodies before sending them to POST /battery/{deviceId}. Presence-based at every level: a command is included only when the device supports it, and within each command a parameter is included only when the device accepts that parameter. Each present entry carries the parameter bounds and the execution shapes (immediate / scheduled / windowed) the device accepts.

​
settings
object

Per-canonical-setting current value and bounds. Presence-based: a field is present when the device exposes that setting, absent when the device does not.