Skip to main content
GET
/
battery
/
{deviceId}
curl
curl --request GET \
  --url 'https://api.amps.ai/battery/device_abc123' \
  --header 'x-api-key: amps_sk_test_xxxxxxxxxxxxxxxxxxxxxxxx'
{
  "success": true,
  "data": {
    "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"
    },
    "conflictStrategies": [
      "cancel_and_replace",
      "queue_after"
    ],
    "commands": {
      "charge": {
        "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": {
        "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": {
        "parameters": {},
        "execution": [
          "immediate",
          "scheduled"
        ]
      },
      "auto.balanced": {
        "parameters": {},
        "execution": [
          "immediate",
          "scheduled"
        ]
      },
      "auto.reserve": {
        "parameters": {},
        "execution": [
          "immediate",
          "scheduled"
        ]
      },
      "auto.export": {
        "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
      }
    },
    "lastAction": {
      "id": "action_def456",
      "command": "charge",
      "state": "completed",
      "createdAt": "2026-05-07T08:15:00.000Z",
      "updatedAt": "2026-05-07T08:18:00.000Z",
      "links": {
        "self": "/actions/action_def456"
      }
    },
    "currentSchedule": null
  },
  "meta": {
    "requestId": "req_8a2Bf3kP",
    "environment": "sandbox",
    "timestamp": "2026-06-02T12:00:00.000Z",
    "latencyMs": 12
  }
}

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.

​
success
boolean
required

Always true for success responses.

​
data
Battery Response · object
required

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.

​
meta
Response Meta · object
required

Metadata attached to every response: the request identifier, the serving environment, the build timestamp, and the server-side latency.