Budget Gate

The Pro+ budget gate lets you attach a simple spend cap to one authorization. It is a launch-safe control for estimated agent action cost, not a full FinOps system.

Budget is not a decision verb. A budgeted check still returns allow, deny, confirm, or escalate.

• Under budget: normal allow, confirm, or escalate
• Over budget: deny with reason: "budget_exceeded"
• No budget on the authorization: normal /check behavior

Configure a budget

Set budget_limit_micros when creating the authorization on a Pro or Enterprise workspace.

{
  "user_id": "usr_8821",
  "agent_id": "research_agent",
  "scopes": [{ "name": "llm.enrich" }],
  "expires_at": "2026-12-31T00:00:00Z",
  "budget_limit_micros": 50000000
}

budget_limit_micros is micro-USD. 50000000 means $50.00. Free and Starter workspaces receive 402 budget_plan_required if they set this field.

The response includes the cap and current spend:

{
  "authorization_id": "auth_01HXZ2A...",
  "created_at": "2026-04-21T14:30:00.000Z",
  "expires_at": "2026-12-31T00:00:00.000Z",
  "budget_limit_micros": 50000000,
  "budget_spent_micros": 0,
  "receipt": {
    "status": "pending",
    "receipt_id": "rcp_01HXZAUTHORIZATION...",
    "ready_at_estimate": "2026-04-21T14:30:01.000Z",
    "url": "https://api.allowly.ai/v1/receipts/rcp_01HXZAUTHORIZATION..."
  }
}

Check with an estimate

For a budgeted authorization, /v1/check requires estimated_cost_micros.

{
  "authorization_id": "auth_01HXZ2A...",
  "scopes": ["llm.enrich"],
  "resource": "lead:984",
  "estimated_cost_micros": 24000,
  "context": {
    "model": "gpt-4.1-mini",
    "input_tokens": 1200
  }
}

For launch, budgeted checks must request exactly one scope. Multi-scope budget estimates are intentionally not supported yet because they need a per-scope estimate map.

Response fields

When budget is evaluated, the scope result includes a budget block.

{
  "decision": "allow",
  "reason": "authorization_granted_scope_active",
  "budget": {
    "limit_micros": 50000000,
    "spent_micros": 120000,
    "estimated_cost_micros": 24000,
    "spent_after_micros": 144000
  },
  "receipt": {
    "status": "pending",
    "receipt_id": "rcp_01HXY...",
    "ready_at_estimate": "2026-04-21T14:32:18.482Z",
    "url": "https://api.allowly.ai/v1/receipts/rcp_01HXY..."
  }
}

If the projected spend would exceed the cap:

{
  "decision": "deny",
  "reason": "budget_exceeded",
  "budget": {
    "limit_micros": 50000000,
    "spent_micros": 49990000,
    "estimated_cost_micros": 24000
  },
  "receipt": {
    "status": "pending",
    "receipt_id": "rcp_01HXY...",
    "ready_at_estimate": "2026-04-21T14:32:18.482Z",
    "url": "https://api.allowly.ai/v1/receipts/rcp_01HXY..."
  }
}

Over-budget denials do not increment budget_spent_micros.

Receipts

Budget details are recorded inside the signed receipt payload under context.budget.

{
  "context": {
    "budget": {
      "limit_micros": 50000000,
      "spent_before_micros": 120000,
      "estimated_cost_micros": 24000,
      "spent_after_micros": 144000
    }
  }
}

The customer-provided estimate is authoritative. Use conservative estimates for high-risk actions, and configure fail-closed SDK fallback for workflows where budget enforcement is required during outages.

Validation behavior

Current scope

Budget checks are authorization-level controls for estimated action cost. They are not a replacement for your billing ledger, invoice reconciliation, or provider-side spend reporting.