List burn exemptions
well_list_burn_exemptionsList the categories a reader can exempt from burn over one window, each with the spend exempting it would remove. This is what the exemption card offers; it measures nothing the sum did not already measure.
Each entry in groups is one category's OUTFLOW in the window: category_key (the id an exemption is matched on), label (the category as the product writes it), amount (a magnitude, never signed) and count (the rows behind it). Sorted by amount descending, so the biggest decision reads first. A category with no outflow in the window is NOT listed — exempting it would remove nothing, so it is not a choice.
total is the sum of groups[].amount and nothing else. unclassified_amount and unclassified_count are the outflow this list cannot offer as a choice: rows carrying no category, which no exemption ever matches, and rows whose category is outside the shared vocabulary, which this read cannot name for a reader. The two are reported together because both leave the reader's choices unable to touch that money — not because the same thing is true of them downstream. total + unclassified_amount is the window's whole outflow, so a reader can see what the choices do not cover. State the unclassified figure whenever it is not zero rather than presenting total as the whole window.
Pass the convention you elected for the burn figure itself. The list and the figure have to sit on one election, and this read deliberately does not make a second one.
partial: true means the underlying sum measured nothing, so groups is empty and nothing is known about the window's spend. Say so and offer to try again, rather than presenting an empty list as a decision. unreadable_rows counts rows whose amount could not be read at all; they are in no figure here.
from is inclusive and to is EXCLUSIVE, so a window of whole months passes the first instant of the month after the last one you want. window echoes both back exactly as you sent them.
Internal transfers are already out. This read keeps only the rows with exactly one leg on an account the workspace owns — the same rule the burn applies — so a movement between the workspace's own accounts never appears here.
currency is the one currency every row in the window shares. A window holding more than one, or holding a row that carries none, is REFUSED with success: false and an error saying which: adding two currencies gives a number denominated in nothing, and no field on this result could say it happened. currency is the EMPTY STRING only when the window held no row at all, and then groups is empty and both totals are zero.
The direction convention is elected ONCE over the whole window, never per category. A window whose rows are overwhelmingly negative stores an outflow as a negative amount, and these figures are that branch. A window that stores outflows as positive magnitudes keeps the direction in a field this grouping does not read, and a window that pools both kinds of feed has no single outflow at all — both are REFUSED with an error naming the counts behind the decision, rather than reported as spend.
offered_categories lists every category key this card offers now. stored_choice is an answer a board block stored for this card: pass the block's binding.scope when it carries both exempt_categories and offered_categories, and omit it otherwise. reuse_stored_choice: true means no category is new since that answer: apply the stored exempt_categories as they stand, and wait for nothing, because the card asks nothing. reuse_stored_choice: false beside a stored choice means new_options names a category the reader never judged: the card shows the stored answer ticked and ticks a new TREASURY_PLACEMENT_OUT or TREASURY_REDEMPTION_IN category and leaves every other new category unticked, and the answer is awaited as on a first run.
Unless the stored choice was reused, take the reader's answer from the card, record it with well_switch_workspace as exempt_categories, and read it back with well_wait_for_selection (kind "exemptions"). The record belongs to this conversation. Another conversation does not read it. Then pass the same keys to well_sum_transactions as exempt_categories to compute the burn without them, and name the exemptions beside the figure so it can be read back.
When the token authorizes one workspace, call this directly — no workspace call is needed first. When it authorizes several, this read will not guess which one you mean: pass workspace_id on the call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | EXCLUSIVE end of the window, ISO-8601 — the first instant after the last month you want. | |
| from | Yes | Inclusive start of the window, ISO-8601 (e.g. 2026-06-01). | |
| convention | Yes | Which sign means money leaving, as YOU elected it for the figure these exemptions apply to — the same election `well_render_burn` takes. This read does not elect its own: a share of positive rows cannot tell a business with revenue apart from two feeds pooled together, and guessing would either refuse ordinary workspaces or total two conventions as one. Pass "signed" when the window's rows are mostly negative for spend, "magnitude" when the feed stores outflows as positive numbers. A "magnitude" window is refused, because direction then lives in a field this read does not group on. | |
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which. | |
| stored_choice | No | The answer a board block stored for this card: the block's `binding.scope`. Omit it outside a board run. | |
| conversation_id | No | The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation. | |
| workspace_scope | No | Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| total | Yes | The sum of groups[].amount, and nothing else. | |
| groups | Yes | ||
| window | Yes | ||
| partial | Yes | True when the sum behind this card measured nothing. `groups` is then empty, so there is no list to choose from: say so and offer to try again. | |
| success | Yes | ||
| currency | Yes | The one currency every row shares; empty only when the window held no row. | |
| next_step | No | What to do with the card this result renders. Added by the dispatcher when the card asks for a click. | |
| pre_ticked | Yes | The options the card starts with ticked. | |
| new_options | Yes | Options listed now that the stored choice did not offer. Empty when no stored choice was passed. Name each one when the card is shown for it. | |
| conversation_id | No | The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation. | |
| newly_connected | No | Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later. | |
| unreadable_rows | Yes | Rows in the window whose amount could not be read. They are in no figure here, including the unclassified one. | |
| offered_categories | Yes | Every category key this card offers now, in the order it lists them. The card records it beside the reader's answer, so a board block can store the two together. | |
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| unclassified_count | Yes | ||
| reuse_stored_choice | Yes | True when a stored choice was passed, the read completed, and no option is new. Apply the stored choice as it stands: the card asks nothing and no wait is owed on it. | |
| unclassified_amount | Yes | Outflow this list cannot offer as a choice: rows with no category, which no exemption ever matches, and rows whose category is outside the shared vocabulary, which cannot be named here. | |
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| conversation_id_source | No | Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened. |