> ## 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.

# Switch a Battery to Auto Balanced

> Hand control of a battery back to the platform with auto.balance. Charges when solar is plentiful, discharges when the home draws power.

## Overview

Use this when the customer has finished a manual override and the device should go back to running itself. A common pattern: a tariff-aware app schedules a windowed charge overnight, then drops the device to `auto.balance` for the day so the battery covers the home as solar comes and goes.

`auto.balance` is the canonical name for the OEM's own self-consumption mode. Push it and Amps maps the verb onto whichever native mode the device exposes for that intent. The device's firmware does the optimisation.

The body is short: no parameters, no window. Use it to drop back to self-managing after a windowed charge or discharge completes.

## Step 1: Push auto.balance

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl -X POST https://api.amps.ai/battery/device_abc123 \
      -H "x-api-key: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{
        "action": {
          "command": "auto.balance"
        }
      }'
    ```
  </Tab>

  <Tab title="Node">
    ```javascript theme={null}
    await fetch("https://api.amps.ai/battery/device_abc123", {
      method: "POST",
      headers: {
        "x-api-key": process.env.AMPS_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        action: { command: "auto.balance" },
      }),
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os, requests

    requests.post(
        "https://api.amps.ai/battery/device_abc123",
        headers={
            "x-api-key": os.environ["AMPS_API_KEY"],
            "Content-Type": "application/json",
        },
        json={"action": {"command": "auto.balance"}},
    )
    ```
  </Tab>
</Tabs>

You get back `202 Accepted`. This is an immediate push (no `start`), so the action lands in `acknowledged` without passing through `scheduled`. The response, like every other, is wrapped in `{ success, data, meta }`.

```json theme={null}
{
  "success": true,
  "data": {
    "id": "act_inflight_002",
    "deviceId": "device_abc123",
    "deviceType": "battery",
    "command": "auto.balance",
    "parameters": null,
    "state": "acknowledged",
    "createdAt": "2026-05-08T11:30:00.000Z",
    "links": { "self": "/actions/act_inflight_002" }
  },
  "meta": { "requestId": "req_2fX6tGjW", "environment": "sandbox", "timestamp": "2026-05-08T11:30:00.000Z", "latencyMs": 95 }
}
```

The response mirrors the command. `auto.balance` is an intent with no constraints, so `data.parameters` is `null`. Track the action at `data.links.self`.

## Step 2: Confirm the mode applied

Once the OEM accepts the write, the action moves to `completed`.

```bash theme={null}
curl -X GET https://api.amps.ai/actions/act_inflight_002 \
  -H "x-api-key: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx"
```

```json theme={null}
{
  "success": true,
  "data": {
    "id": "act_inflight_002",
    "deviceId": "device_abc123",
    "deviceType": "battery",
    "command": "auto.balance",
    "parameters": null,
    "state": "completed",
    "result": { "success": true, "message": "Mode applied" },
    "errorCode": null,
    "errorMessage": null,
    "createdAt": "2026-05-08T11:30:00.000Z",
    "updatedAt": "2026-05-08T11:30:04.000Z",
    "acknowledgedAt": "2026-05-08T11:30:01.000Z",
    "completedAt": "2026-05-08T11:30:04.000Z",
    "start": null,
    "end": null,
    "links": { "self": "/actions/act_inflight_002" }
  },
  "meta": { "requestId": "req_3gY7uHkX", "environment": "sandbox", "timestamp": "2026-05-08T11:30:05.000Z", "latencyMs": 12 }
}
```

## Step 3: Verify the live state

Read the device to see the mode in action. `data.state.status` reports `idle`, `charging`, or `discharging` depending on solar output and home demand.

```bash theme={null}
curl -X GET https://api.amps.ai/battery/device_abc123 \
  -H "x-api-key: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx"
```

```json theme={null}
{
  "success": true,
  "data": {
    "id": "device_abc123",
    "vendor": "foxess",
    "sync": { "available": true, "lastPulledAt": "2026-05-08T11:30:09.000Z" },
    "metadata": { "model": "FoxESS H1-5.0-E", "source": "projection" },
    "state": {
      "status": "charging",
      "capacity": 10.4,
      "level": 67,
      "chargeRate": 1.6,
      "dischargeLimit": 10,
      "currentMode": "auto.balance"
    },
    "conflictStrategies": ["cancel_and_replace", "queue_after"],
    "lastAction": {
      "id": "act_inflight_002",
      "command": "auto.balance",
      "state": "completed",
      "createdAt": "2026-05-08T11:30:00.000Z",
      "updatedAt": "2026-05-08T11:30:04.000Z",
      "errorCode": null,
      "errorMessage": null,
      "links": { "self": "/actions/act_inflight_002" }
    },
    "currentSchedule": null
  },
  "meta": { "requestId": "req_4hZ8vIlY", "environment": "sandbox", "timestamp": "2026-05-08T11:30:09.000Z", "latencyMs": 286 }
}
```

The battery is self-managing from this point. It charges when solar exceeds home draw, discharges when production drops, all without further API calls.

## Other auto modes

Three auto variants share the same shape. Pick by intent.

| Command        | Intent                                                     |
| -------------- | ---------------------------------------------------------- |
| `auto.balance` | Maximise self-consumption from solar.                      |
| `auto.reserve` | Hold capacity in reserve for grid outages.                 |
| `auto.export`  | Maximise grid export when the export tariff is attractive. |

Switch between them with the same body, varying only `command`. Not every device supports every auto mode. Check `commands` on the device read before pushing.

## What next

<CardGroup cols={2}>
  <Card title="Schedule a charge for later" icon="moon" href="/guides/cookbook/schedule-charge-later">
    Combine an overnight charge with auto.balance for the day.
  </Card>

  <Card title="Cancel an action" icon="x" href="/guides/cookbook/cancel-action">
    Drop back to auto by cancelling an in-flight schedule.
  </Card>

  <Card title="Canonical actions" icon="book-open" href="/concepts/canonical-actions">
    Why auto modes are intent declarations, not OEM passthroughs.
  </Card>

  <Card title="Subscribe to webhooks" icon="webhook" href="/guides/cookbook/subscribe-webhooks">
    Get push.completed events the moment the mode applies.
  </Card>
</CardGroup>

<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{__html: JSON.stringify({
"@context": "https://schema.org",
"@type": "HowTo",
"name": "Switch a Battery to Auto Balanced",
"description": "Hand control of a battery back to the platform with auto.balance. Charges when solar is plentiful, discharges when the home draws power.",
"step": [
{
  "@type": "HowToStep",
  "name": "Step 1: Push auto.balance",
  "position": 1
},
{
  "@type": "HowToStep",
  "name": "Step 2: Confirm the mode applied",
  "position": 2
},
{
  "@type": "HowToStep",
  "name": "Step 3: Verify the live state",
  "position": 3
}
]
})}}
/>