Skip to content

Test a spending limit in shadow mode before enforcing it

A limit in shadow mode never blocks a call. Agent FinOps checks every supported call against it exactly as it would in enforce mode and records the result on the call’s receipt. You see which customers, workflows and runs the limit would have stopped, and what that spend cost, before anything is denied.

When the results look right, switch the limit to enforce.

Shadow mode is part of hosted Agent FinOps on the Control path (POST /v1/budget/reserve). It needs kazenai 1.2.0 connected to Agent FinOps with the Control settings in Configuration; the mode itself is set on the limit, not in the SDK.

Each limit has a mode: enforce (the default) or shadow.

  • Enforce wins. If any enforce-mode limit on a call would deny it, the call is denied exactly as before. Shadow-mode limits never change that outcome.
  • Shadow limits only annotate. The call runs, and its receipt says what the shadow-mode limit would have decided.
  • Shadow predicts enforcement for the same traffic. Every balance keeps two ledgers: real spend, and an enforced-world ledger that counts only calls enforcement would have admitted. Shadow decisions use the enforced-world ledger. So 50 calls of $0.25 against a $5.00 shadow limit show 20 would-allow and 30 would-deny, the same calls an enforce-mode limit would deny. (If shadow decisions used real spend, every call after the first denial would also be flagged, overstating what enforcement does.)

What shadow mode cannot show is how your application behaves after a real denial. Under enforcement a run may stop earlier and make fewer calls.

Set enforcement_mode when you create or update a limit:

Terminal window
curl -X POST "$FINOPS/v1/org/$ORG/budget-limits" \
-H "X-API-Key: $ADMIN_KEY" -H "Content-Type: application/json" \
-d '{
"workspace_id": "prod-api",
"dimension": "business_subject",
"dimension_id": "acct-42",
"window": "daily",
"limit_usd": 5.00,
"enforcement_mode": "shadow",
"audit_reason": "First rollout: observe before enforcing"
}'
  • Omit enforcement_mode on an update to keep the limit’s current mode. A new limit without it enforces.
  • Changing the mode is an ordinary update: it supersedes the active version and bumps policy_version, and it needs an audit_reason and the current expected_updated_at_ms.
  • In the dashboard, Policy admin has a Mode selector, and shadow limits show a SHADOW badge.

On each receipt. A call that a shadow limit would have denied is still decision: allow with reason_code: allowed_with_reservation, plus:

"enforcement": {
"mode": "shadow",
"shadow": {
"would_decision": "deny",
"reason_code": "insufficient_capacity",
"determining_constraint": {
"scope": "business_subject",
"outcome": "deny",
"policy_id": "budget.business_subject.acct-42.daily",
"policy_version": "1",
"detail": "shadow: insufficient remaining capacity on business_subject"
},
"virtual_remaining_capacity_usd_micros": 150000
}
}

mode is mixed when enforce-mode and shadow-mode limits both applied. Each entry in evaluated_policies also carries its mode. Receipts where only enforce-mode limits applied have no enforcement block and are unchanged.

The reserve response carries a short summary as shadow (would_decision, enforcement_mode, policy_id, policy_version).

Filter receipts: GET /v1/org/{org}/decision-receipts?shadow=would_deny. The filter returns every receipt a shadow-mode limit would have denied, including requests an enforce-mode limit actually denied. In the dashboard, Run receipts marks allowed rows SHADOW · would deny (the call ran) and denied rows shadow: would also deny (the request did not run).

The shadow report groups the calls that ran but that a shadow-mode limit would have refused, with their settled cost:

Terminal window
curl "$FINOPS/v1/org/$ORG/shadow-report?group_by=business_subject&from=2026-10-01T00:00:00Z" \
-H "X-API-Key: $KEY"
Parameter Values
group_by business_subject (default), workflow, feature, policy
from, to ISO 8601 UTC, to exclusive. Default: the last 30 days. At most 92 days apart
workspace_id Optional
format json (default) or csv

Each group has would_deny_calls, runs, estimated_usd_micros, settled_usd_micros and unsettled_calls. Groups are sorted by settled cost; at most 1,000 are returned (groups_truncated says when there were more), and the totals always cover all of them:

Total Counts
shadow_evaluated_requests Every request a shadow-mode limit checked, allowed or denied
shadow_executed_calls Those that were allowed and ran
would_deny_calls Calls that ran but that a shadow-mode limit would have refused
enforced_denials Requests an enforce-mode limit denied that shadow would also have denied. They did not run and are never counted as executed
  1. Preview the limit first. POST /v1/org/{org}/budget-limits/preview reports, for each shadow-mode limit, actual_remaining_usd_micros and switch_to_enforce_would_deny. Enforcement uses real spend, so a limit whose customer is already over it starts denying immediately. Pass the limit’s scope (business_subject_ref, feature_id, workflow_id, actor_id, team) so the preview evaluates it. The dashboard’s Switch to enforce button runs this check before it saves; if it can’t check a limit’s current spend, it says so and asks you to confirm.
  2. Update the limit with "enforcement_mode": "enforce".

Switching from enforce to shadow mid-window is also safe: the enforced-world ledger is kept for every limit, so shadow decisions continue from the right place.

  • Outages follow the organization’s setting, not the limit’s mode. If Agent FinOps is unreachable, a monitored call is refused (BudgetUnavailable) unless an admin chose fail-open for the organization. See Configuration.
  • Local SDK budgets (monitor(..., max_budget_usd=...)) and the request gate always enforce. Shadow mode applies to hosted limits.
  • The loop guard records by default: a repeated request writes a finops.loop.anomaly event and still runs. With monitor(..., loop_guard="block") it refuses the request with LoopDetected, in shadow mode too, and that refusal isn’t a limit decision, so it isn’t in the shadow report.
  • The legacy check path (POST /v1/budget/check) has no enforced-world ledger and treats a shadow-mode limit as enforced.
  • Real spend is always recorded, and the Stripe meter export sends it as usual.