> ## Documentation Index
> Fetch the complete documentation index at: https://docs.allocait.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Plan a rebalance

> See how far each class is from its band and the amounts that close the gap.

A rebalance preview shows how far each class outside its band is from its aim, and the pro rata amounts that would close the gap. In the app the amounts use Allocait's stored quotes; through Claude or the API they use only prices you supply. Allocait cannot approve, stop or place an order. After you trade elsewhere, [update what you hold](https://docs.allocait.app/guides/update-holdings.md) so your numbers stay current.

## What it aims at

For each class outside its [allocation band](https://docs.allocait.app/concepts/allocation-bands.md), the preview aims at:

* The class's own **target**, if you set one on the rule.
* Otherwise, the **midpoint** of the band.

A target always sits inside the band: Allocait refuses one outside it (see [Targets](https://docs.allocait.app/concepts/targets.md)). The preview never aims beyond the band.

## In the app

**1. Open Rebalance**

Select the portfolio and scenario in the top bar, then go to **Rebalance**.

**2. Read the amounts**

Each row is an asset class. Classes outside their band come first, largest dollar amount first. **Allocation** shows the class's share and where it aims, labeled a target if you set one and the midpoint if you didn't. **Change to reach band** shows the pro rata amount, in dollars and shares. A class inside its band shows its status instead of an amount. Open a class to see its holdings and roughly how many shares each one moves. The method note above the table says how the amounts are calculated.

**3. Trade elsewhere, if you choose**

Allocait places nothing. If you act on the amounts, do it at your brokerage.

**4. Record what you hold**

Choose **Record trades**. The dialog lists each holding the amounts move, with its new total filled in. Enter what you now hold, untick the holdings you didn't change, and record the rest. Cash moves at the latest quote Allocait has stored, and each change is logged to Actions. You can also [update holdings](https://docs.allocait.app/guides/update-holdings.md) one at a time on the Positions page.

## Through Claude or another agent

Through MCP, `get_portfolio_snapshot` with `include_rebalance` and your prices for `holdings_to_price` returns a `rebalance` block. It uses the same arithmetic as the Rebalance page, at the prices you give. The block's `trades` list is the wire name for the amounts. Each row has an `action` (`BUY` or `SELL`) and a `direction` (`ADD` or `REDUCE`): an amount that adds to or removes from a holding. Without `include_rebalance` the snapshot has no `rebalance` block, and a check answers from `compliance`. If the portfolio has no active scenario, the checks ask for a `scenario_id` and Allocait doesn't pick one (see [Scenarios](https://docs.allocait.app/concepts/scenarios.md#the-active-scenario)).

To see what one specific change does to your rules, use [Check before you trade](https://docs.allocait.app/guides/check-before-you-trade.md).

## Through the REST API

`POST /rebalance/preview` takes a portfolio, a price for every non-cash position you hold, and optionally a scenario. A held option with a mark needs no price. Left out, the scenario is the portfolio's active one, and a portfolio with none set is refused. Illustrative example. The figures are hypothetical, not a recommendation.

```bash theme={null}
curl -X POST "https://allocait.app/api/v1/rebalance/preview" \
  -H "x-api-key: $ALLOCAIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "portfolio_id": "YOUR_PORTFOLIO_ID",
    "scenario_id": "YOUR_SCENARIO_ID",
    "prices": { "ALFA": 181.5, "ECHO": 52.7, "GOLF": 62.3 }
  }'
```

The response has these parts:

* `trades`: the amounts, one row per holding that carries a class's move.
* `resulting_classes`: each class's share of the portfolio after the amounts, with Cash included.
* `unresolved`: each class still outside its band after the amounts, with a `reason`: `outside_band_after_trades`, `cash`, `zero_price` (every priced holding in it is priced at 0) or `no_priced_holdings` (it has nothing to trade).
* `not_rebalanced`: each short and each option, once, with `symbol`, `asset_class` and `reason` (`short` or `option`). An option is a holding in the Options class.

How the amounts are set:

* A class's move is the gap on its net value (shorts subtract), spread over its long holdings outside Options only, so one long can carry the whole gap.
* Amounts drawn from a class land in Cash. They don't resize holdings, so size violations stand.
* A class with no priced long holding outside Options has no amount, and appears in `unresolved` if it stays outside its band.
* A portfolio worth zero or less has no percentages, so the response has no amounts and each `resulting_pct` is null; `total_value` is still reported, signed.

`POST /portfolio/snapshot?include_rebalance=true` returns the same block inside the snapshot. Without the flag the snapshot has no `rebalance` block.

Prices must cover every non-cash position in the portfolio, except a held option with a mark or one past its expiry, or the call fails with a 400 listing `missing_symbols`. Allocait doesn't fill in a symbol you left out from its own market data. See [Prices](https://docs.allocait.app/concepts/prices.md) for why, and the [API introduction](https://docs.allocait.app/api/introduction.md) for the full response shape.

## Next steps

* [Targets](https://docs.allocait.app/concepts/targets.md) covers what a preview aims at.
* [Allocation bands](https://docs.allocait.app/concepts/allocation-bands.md) explains the statuses a preview reads.
* [Status words](https://docs.allocait.app/concepts/status-words.md) maps those statuses to API values.
* [Check before you trade](https://docs.allocait.app/guides/check-before-you-trade.md) tests one change against your rules.
* [Update holdings and cash](https://docs.allocait.app/guides/update-holdings.md) records what you hold after you trade.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.