Pull

Read what a device is doing now, what it can do, and what Amps last told it to do. The read shape is the same for every device type; only the state fields change.

Read a device

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

{
  "success": true,
  "data": {
    "id": "device_abc123",
    "vendor": "example_vendor_a",
    "sync": { "available": true, "lastPulledAt": "2026-06-01T10:14:23.000Z" },
    "metadata": { "model": "Hybrid 5kWh", "source": "cache", "cacheType": "normal" },
    "state": {
      "status": "charging",
      "level": 50,
      "capacity": 10.4,
      "chargeRate": 2.4,
      "dischargeLimit": 10,
      "currentMode": "charge"
    },
    "commands": {
      "charge": {
        "parameters": { "target": { "unit": "percent", "min": 0, "max": 100 } },
        "execution": ["immediate", "scheduled", "windowed"]
      }
    },
    "conflictStrategies": ["cancel_and_replace", "queue_after"],
    "settings": { "discharge_floor": { "value": 10, "unit": "percent", "min": 0, "max": 100 } },
    "lastAction": {
      "id": "action_FoRvdqounP",
      "command": "charge",
      "state": "completed",
      "links": { "self": "/actions/action_FoRvdqounP" }
    },
    "currentSchedule": null
  }
}

The same route exists for every type: /battery, /ev-charger, /hvac, /solar-inverter, /vehicle.

Field
`state`	What the device is doing now. Fields per type are listed below.
`sync`	`available` is `false` when the reading is a stored fallback. `lastPulledAt` is when the reading was taken from the device.
`metadata`	`model`, plus where the reading came from. See Freshness.
`commands`, `conflictStrategies`	What the device accepts. See Capabilities.
`settings`	Persistent configuration with current values. See Settings. Batteries and EV chargers only.
`sessions`	EV chargers only. `true` when the charger reports charging-session history at `/ev-charger/{deviceId}/sessions`.
`lastAction`	Summary of the most recent action you sent to this device. `null` until the first one.
`currentSchedule`	Always `null` for now.

Solar inverters and vehicles are read-only. Their reads carry id, vendor, sync, metadata, and state, and nothing else.

What the device is doing vs what it was told

state.status is what the battery is doing. state.currentMode is the command it’s running. They can differ: a charge whose target is already met reads status: "idle", currentMode: "charge", chargeRate: 0. EV chargers report the same split with isCharging and activeControlMode. Compare state with lastAction to spot changes made outside Amps, such as the homeowner switching mode in the manufacturer’s app.

`lastAction`

A summary for rendering a device card in one call. For parameters and the full result, follow links.self to GET /actions/{id}.

{
  "id": "action_FoRvdqounP",
  "command": "charge",
  "state": "failed",
  "createdAt": "2026-06-01T09:15:00.000Z",
  "updatedAt": "2026-06-01T09:15:32.000Z",
  "errorCode": "DEVICE_OFFLINE",
  "errorMessage": "The device is currently offline at the manufacturer.",
  "links": { "self": "/actions/action_FoRvdqounP" }
}

updatedAt is the last state change. errorCode and errorMessage are null unless state is failed. A just-sent action can take a moment to appear here, so read it by id if you need its state straight after a push.

Freshness

Live reads are cached. metadata.source tells you where a reading came from.

`metadata.source`	Meaning	`sync.available`
`cache`	A recent reading. Up to 15 minutes old, or 1 minute with `?expedite=true`. `cacheType` says which.	`true`
`live`	Read from the device during this request.	`true`
`fallback`	The device couldn’t be reached, so this is the last stored reading. Check `sync.lastPulledAt`.	`false`
`projection`	Simulated sandbox state. See Sandbox.	`true`

For fresher data, add ?expedite=true. It returns a reading no more than a minute old, calling the manufacturer if needed. Use it sparingly.

curl "https://api.amps.ai/battery/device_abc123?expedite=true" \
  -H "x-api-key: $AMPS_API_KEY"

A completed push doesn’t refresh the cache. To react to a command, use the push.completed webhook, then read with ?expedite=true if you need the new state. In live, settings is included when the reading comes from the device (source: "live") and omitted on cached and fallback readings. A setting the device reports in an unusable form, or outside its declared range, is left out rather than shown. When Amps has temporarily paused reads for a manufacturer, you get the last stored reading with metadata.degraded: true, or 503 CAPABILITY_PAUSED. Retry with backoff. If the device is offline or unknown at the manufacturer, the read returns an error (DEVICE_OFFLINE, DEVICE_NOT_FOUND) instead of stale data. See Error codes.

List devices

curl "https://api.amps.ai/battery?userId=user_abc123&limit=20&offset=0" \
  -H "x-api-key: $AMPS_API_KEY"

{
  "success": true,
  "data": {
    "items": [{ "id": "device_abc123", "state": { "status": "idle", "level": 67 }, "lastAction": null }],
    "pagination": { "limit": 20, "offset": 0, "total": 1, "hasMore": false }
  }
}

Query
`userId`	Only devices linked by this end user.
`limit`	1 to 50. Default 10.
`offset`	Default 0.

List entries carry the last stored reading, commands, conflictStrategies, and lastAction, but not settings. For current state, read the device by id.

Sandbox

Sandbox devices are simulated. Batteries, EV chargers, and thermostats report source: "projection", and their state follows the commands you send: push charge and the next read shows status: "charging" with level rising toward the target. No cache, no waiting.

Values in motion change between reads. Compare against the command you sent, not an exact earlier number.
A windowed command is active between start and end, then the device goes idle and holds where the window left it.
With no commands, devices follow a daily pattern on UTC time, for example batteries charge around midday UTC.

Solar inverters and vehicles follow the UTC daily pattern only, since they take no commands. Their reads report cache or live.

State fields by device type

Battery

Field	Unit	Meaning
`status`		`charging`, `discharging`, `idle`, or `standby`.
`level`	percent	State of charge, 0 to 100.
`capacity`	kWh	Total capacity.
`chargeRate`	kW	Current charge rate. Negative when discharging.
`dischargeLimit`	percent	Discharge limit.
`currentMode`		The command the battery is running, such as `charge` or `auto.balance`. Omitted when the mode has no canonical equivalent.

EV charger

Field	Unit	Meaning
`status`		`available`, `charging`, `discharging`, `scheduled`, `error`, or `offline`.
`isConnected`		A vehicle is plugged in.
`isCharging`		The charger is delivering power to the vehicle now.
`currentPower`	kW	Current power. Negative when exporting from the vehicle.
`maxCurrent`	A	Maximum current the charger can deliver.
`powerRateLimit`	kW	Configured maximum charging power.
`sessionEnergy`	kWh	Energy delivered in the current session.
`phases`		Supply phases in use, 1 to 3.
`voltage`	V	Supply voltage.
`notChargingReason`		Why a plugged-in vehicle isn’t charging: `vehicle`, `target_reached`, `charger`, `load_management`, `authorization`, `schedule`, or `unknown`.
`activeControlMode`		The command the charger is running, such as `charge` or `auto.charge_tariff`.

Only status, isConnected, and isCharging are always present. The rest are omitted when the charger doesn’t report them, never sent as zero.

HVAC

Field	Unit	Meaning
`temperature`	°C	Current temperature.
`active`		Heating or cooling right now.
`heatSetpoint`	°C	Heats below this.
`coolSetpoint`	°C	Cools above this.
`mode`		`heat`, `cool`, `auto`, or `off`.
`holdType`		`permanent` when a fixed setpoint overrides the device’s own program, `schedule` when it’s following it.

Solar inverter

Field	Unit	Meaning
`status`		`producing`, `idle`, `night_mode`, `error`, or `offline`.
`producing`		Producing power now.
`currentPower`	kW	Current AC output.
`energyTotal`	kWh	Lifetime production.

Vehicle

Field	Unit	Meaning
`batteryLevel`	percent	State of charge, 0 to 100.
`range`	miles	Estimated remaining range.
`plugged`		Plugged in to a charger.
`charging`		Drawing charge now.
`fullyCharged`		Reached `chargeLimit`.
`batteryCapacity`	kWh	Usable capacity.
`chargeLimit`	percent	Configured charge limit.
`chargeRate`	kW	Current charge rate. Negative when discharging.
`chargeTimeRemaining`	minutes	Time to reach `chargeLimit`.
`maxCurrent`	A	Maximum current the vehicle accepts.

Next steps

Capabilities

Read commands to build a valid push.

Push

Send commands and track actions.

Webhooks

React to completed actions instead of polling.

Settings

Read and change persistent device configuration.

Get started

API Reference

Guides

Cookbooks

Read a device

What the device is doing vs what it was told

`lastAction`

Freshness

List devices

Sandbox

State fields by device type

Battery

EV charger

HVAC

Solar inverter

Vehicle

Next steps

Capabilities

Push

Webhooks

Settings

​Read a device

​What the device is doing vs what it was told

​lastAction

​Freshness

​List devices

​Sandbox

​State fields by device type

​Battery

​EV charger

​HVAC

​Solar inverter

​Vehicle

​Next steps

Capabilities

Push

Webhooks

Settings

Read a device

What the device is doing vs what it was told

`lastAction`

Freshness

List devices

Sandbox

State fields by device type

Battery

EV charger

HVAC

Solar inverter

Vehicle

Next steps