Measure a category against its usual month
well_measure_category_trendMeasure ONE spending category for one month against its usual month: the month total, the usual amount, and the difference. It draws no card.
Call it when the person asks how much they spent on one category in a month, or how a month compares to usual ("how much did I spend on groceries this month compared to usual?"). For several categories at once, or for a total by category, use well_sum_transactions instead.
"Usual" is the mean of the 3 full months before the month. A month with no row of the category counts 0. Read baseline_complete before you call the figure usual: when it is false, some of those months had no transaction in scope at all, so say which months had data (baseline_activity) and do not call the mean usual.
The month defaults to the running month in UTC. The running month is partial: month_complete is false, so say the month is not over. A month after the running month is refused.
Figures are per currency, with no conversion: one entry in currencies per currency, at most 10. Never add two currencies together. An empty currencies means the category has no row in the whole window. A month amount is the net of the category's money in and money out, as a magnitude: spend minus refunds on a feed that keeps one sign convention. When a large share of the category's rows over the window is negative and a large share is positive, the workspace pools a feed that signs its outflows with one that stores magnitudes, and no single spend figure exists: the call refuses with refusal_reason: "mixed_sign_conventions" and the two row counts, and measures nothing.
uncategorized_in_month.count is the rows of the month with no category at all; a row filed under a category the person typed is not counted. Some of them can belong to this category, so the month total is a floor when the count is not 0: say so. excluded_malformed counts the rows with an amount that could not be read.
The category list depends on the workspace. A personal space files household categories, a company workspace business categories, and both file the shared ones. A category outside the workspace's list returns refusal_reason and allowed_categories, and nothing is measured. A personal space shows some shared keys under its own name: TRAVEL_TRANSPORT ("Transport & travel"), MEALS_ENTERTAINMENT ("Restaurants & bars"), BANK_FX_PAYMENT_PROCESSING_FEES ("Bank fees"), TREASURY_PLACEMENT_OUT ("Savings & investments (out)"), TREASURY_REDEMPTION_IN ("Savings & investments (in)"), INVESTMENT_INTEREST_INCOME ("Interest"), LOAN_DRAWDOWNS_REPAYMENTS ("Loans & credit"), INTER_ACCOUNT_TRANSFER_SAME_ENTITY ("Transfers between my accounts"), FX_CONVERSION_PRINCIPAL ("Currency exchange"), UNCATEGORISED_SUSPENSE ("Uncategorised"). Name a category with category.label or category.names from the result, never with the key.
scope defaults to own: the workspace's own transactions. own_and_adopted adds the rows a parent workspace shared with it.
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 |
|---|---|---|---|
| month | No | The month to measure, `YYYY-MM`. Omit for the running month in UTC. A later month is refused. | |
| scope | No | `own` (the default) for the workspace's own rows, `own_and_adopted` to add the rows a parent shared. | |
| category | Yes | The catalog key of ONE category. A personal space names some shared keys differently: TRAVEL_TRANSPORT ("Transport & travel"), MEALS_ENTERTAINMENT ("Restaurants & bars"), BANK_FX_PAYMENT_PROCESSING_FEES ("Bank fees"), TREASURY_PLACEMENT_OUT ("Savings & investments (out)"), TREASURY_REDEMPTION_IN ("Savings & investments (in)"), INVESTMENT_INTEREST_INCOME ("Interest"), LOAN_DRAWDOWNS_REPAYMENTS ("Loans & credit"), INTER_ACCOUNT_TRANSFER_SAME_ENTITY ("Transfers between my accounts"), FX_CONVERSION_PRINCIPAL ("Currency exchange"), UNCATEGORISED_SUSPENSE ("Uncategorised"). | |
| 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. | |
| 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 | ||
| month | No | ||
| scope | Yes | ||
| window | No | ||
| success | Yes | ||
| category | No | ||
| currencies | No | ||
| month_complete | No | ||
| refusal_reason | No | ||
| baseline_months | No | ||
| 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. | |
| month_boundaries | No | ||
| baseline_activity | No | ||
| baseline_complete | No | ||
| allowed_categories | No | With refusal_reason: the categories this workspace files and is offered. Send `label` back; `name` is how the workspace shows it. | |
| excluded_malformed | No | ||
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| workspace_audience | No | ||
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| currencies_truncated | No | ||
| 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. | |
| uncategorized_in_month | No |