Get a mandate's remaining budget (ALPHA)
Alpha — early access.
How much of this standing limit is LEFT right now — what has already been spent under it, what is already earmarked by scheduled payments that have not fired yet, and therefore what remains.
The mandate’s rule tells you the ceilings; this tells you the consumption. Read it BEFORE you schedule a payment: without it, an over-budget payment is only discovered when the mandate gate denies it at its due date, which is days later, with the payee unpaid and no earlier signal to anyone.
Both cap flavours are reported, and both must be honoured. per_target lines are metered against the per-payee caps (max_amount_per_target_in_window, max_count_per_target_in_window); aggregate lines roll every payee up into one line per window bucket and are metered against the agent-wide caps (max_amount_in_window, max_count_in_window). A mandate whose only ceiling is the aggregate one has no per-payee headroom to report, and a caller reading only the per_target lines would schedule straight through the agent’s overall limit.
Open earmarks are included on purpose. A payment that is scheduled but unfired has not spent anything yet, but it WILL at its due date, so budget it does not leave you is budget you do not have. Earmarks are bucketed by the window their due date falls in — a payment due next month consumes NEXT month’s bucket — and a past-due one is clamped into the current bucket, since that is the budget it will actually consume when the cron reaches it.
A remaining_amount of "?" means the figure could not be summed, and MUST be treated as no headroom. It appears when a stored amount or cap in that bucket does not parse as a decimal. The mandate gate fails CLOSED on exactly that data, so a payment sent against a "?" bucket will be denied; reporting a number instead would promise budget that does not exist. remaining_count is unaffected — counts never degrade.
This is ADVISORY, not a reservation. Nothing here holds budget for you, and a concurrent payment can consume the headroom between this read and your write. The gate remains the authority. Use it to refuse what would obviously be denied, not to conclude that a payment is now guaranteed.
Authorizations
Path Parameters
Response
The mandate's budget as of as_of.
A mandate's remaining spend budget at a point in time. Advisory: nothing here reserves budget, and the mandate gate remains the authority at fire time.
The version whose caps these figures are metered against. Amending a mandate changes the caps but NOT the spend — usage accrues to the mandate, so a raised limit leaves the window's consumption intact and a lowered one can leave zero remaining rather than a negative balance.
Unix time the windows were derived and the sums taken. Budget is a function of time — a MONTHLY bucket empties at the rollover — so the figures below are only interpretable against this instant.
The rule's window verbatim (NONE, DAILY, WEEKLY, MONTHLY) — the period each bucket spans and the cadence at which budget resets. NONE is a lifetime cap: one bucket, labelled lifetime, that never resets.
Per-payee lines, metered against max_amount_per_target_in_window and max_count_per_target_in_window. Every configured payee appears for the current window even if it has never been paid, so an empty budget is reported as zeros rather than as a missing line.
One line per window bucket summing EVERY payee, metered against the agent-wide max_amount_in_window and max_count_in_window. This is the ceiling on the agent as a whole; honour it alongside per_target, never instead of it.