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

# Labels

> A label is a name you keep research under, such as an index or a macro series, that Allocait never treats as a security

A label is a name you use for recorded research. Allocait files no class for it, holds no quote for it and never lets you hold or trade it.

Use a label when the name you track is not a security in your account. A research source may print a name that matches a ticker of an unrelated security. If you filed that name from the catalog, Allocait would price the namesake. A label keeps the name and drops the price.

## Make a label

In the app, add a name to a watchlist with **Add as a label**. For a name already on a list, use **Treat as label** on its row, or **Treat as security** to undo it.

An agent sends `label: true` on a watchlist item in `save_watchlist`. `list_watchlists` marks a label with `label: true`. Leaving `label` out keeps the stored state. Sending `false` makes the name a security again, and its class stays empty until you set one.

A label belongs to your account only. Another account may hold the same name as a security.

## What a label can do

* Sit on a watchlist.
* Carry Input values, appear in playbooks and charts, and have monitors on its recorded levels.

Allocait adds no catalog check to those. Any name works there.

## What a label never is

* **Never filed or classed.** Its watchlist row has no asset class.
* **Never held or traded.** A holding or a `check_trades` change that names it is refused.
* **Never priced.** A label adds no price feed subscription and no daily close request for your account, and the snapshot, standing and monitors read no stored quote under its name. A security with the same name in another account isn't affected.
* **Never in `standing` with a price state.** Its monitor state is `null`. A monitor on a label reads a price only when the caller supplies one for that call. See [Standing](https://docs.allocait.app/concepts/standing.md).

## Refusals

Every refusal is `INVALID_INPUT`, with a plain sentence, except the limit:

* A name you hold in a portfolio can't become a label.
* A label can't be held, traded or given a class.
* A name used as the stand-in price symbol of a watchlist row can't become a label.
* A label's name must use letters, digits, dot or dash, up to 20 characters, or a pair like `ALFA/BRAV`.
* Each account has a limit on labels. Past it, the answer is `TIER_LIMIT_EXCEEDED`, which says only that the account reached its limit.

See [Errors](https://docs.allocait.app/claude/errors.md) for what each code means.

## Next steps

> [card] [Tools reference](https://docs.allocait.app/claude/tools/watchlists.md)
>
> `save_watchlist` and `list_watchlists`.

> [card] [Standing](https://docs.allocait.app/concepts/standing.md)
>
> How a label reads in `standing`.


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