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

# Monitors

> Check a symbol's daily close against a level or range you record.

A monitor compares a symbol's price with a level or range you recorded in an [Input](https://docs.allocait.app/concepts/inputs.md). Allocait reports the result as a state. A [webhook](https://docs.allocait.app/guides/webhooks.md) endpoint you add can receive close events. A monitor never places or stops an order.

## Modes

A monitor has one mode.

* `ABOVE`: the level is a ceiling. A close above it is a break.
* `BELOW`: the level is a floor. A close below it is a break.
* `RANGE`: a low Input and a high Input. A close outside the range is a break.
* `NEAR`: reports how close the price is to the level. It has no break and no close event.

A monitor with a high Input defaults to `RANGE`, and one without defaults to `ABOVE`. Its symbols come from the portfolio's holdings, a watchlist, a custom list of up to 50, or one symbol. A symbol can be a [label](https://docs.allocait.app/concepts/labels.md), which has no price state unless a caller supplies a price.

## Price states

A priced monitor reads one state for each symbol: `above_level`, `below_level` or `at_level` for one level, and `below_range`, `above_range`, `in_range`, `at_low` or `at_high` for a range. A symbol with no price or no recorded level has no state.

Set `threshold_pct` (0 to 100) to say how near counts as near. Then the states `near_level`, `near_low` and `near_high` can appear. With no `threshold_pct`, no `near_*` state shows. Allocait types no default threshold.

## Close state

After Allocait records a day's closes, it checks each monitor's symbols against the new daily close. It checks only symbols that have a recorded daily close, so a label, or a symbol with no recorded close, isn't checked. A close past the level (above for `ABOVE`, below for `BELOW`, outside for `RANGE`) is a break:

* The first break moves the symbol to `CONFIRMED`, and `consecutive_closes` counts the breaks in a row.
* A later close back on the other side moves it to `CLEARED`, and the count returns to 0.
* A day whose high or low went past the level while the close stayed on the compliant side is a retrace, not a break. Like any close that is not a break, it sets the state to `CLEARED` and the count to 0.

A `close_state` of `null` means no close has been checked yet. `NEAR` monitors have no close state. The check can widen the level by a confirmation buffer, shown as `buffer_pct` in a webhook payload. No app screen, tool or REST call sets it, so it reads 0.

The check reads the level you recorded most recently. `recorded_low_date` (and `recorded_high_date` for a range) names the date of the entry that level came from. It is a fact, `null` when no entry exists, and Allocait computes no age or staleness from it.

## Conditions

A monitor can list conditions: an Input and the value that counts as Met. The app shows each as Met or Not met. They are display only. They filter no reading and don't change what the close check reports.

## Where you see states

* The app shows each monitor with its state.
* With a signed-in connection, `standing.monitors` carries `state`, `close_state`, `consecutive_closes` and `last_evaluated_date`, with no price or distance. See [Standing](https://docs.allocait.app/concepts/standing.md).
* With a price list you supply, the snapshot also returns the monitor readings. Allocait supplies no market price to an agent.
* A [webhook](https://docs.allocait.app/guides/webhooks.md) can send `monitor.confirmed`, `monitor.retraced` and `monitor.cleared` events at the close.

## For agents

> [!NOTE]
>
> `save_monitor` creates or changes a monitor and `delete_monitor` deletes one. Read monitors from `get_portfolio_snapshot`, which shows their settings and states. A monitor level needs an Input of type number, decimal or percentage. The server instructions tell an agent with no person present to change no monitor and to list in its brief what it would change. Allocait does not block the write.

## Next steps

* [Inputs](https://docs.allocait.app/concepts/inputs.md): record the levels a monitor reads.
* [Webhooks](https://docs.allocait.app/guides/webhooks.md): the monitor events and their payloads.
* [Run a scheduled brief](https://docs.allocait.app/guides/scheduled-brief.md): report only what changed.


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