Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.polaxis.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Budget Controls

Set hard spending limits on your agents. Auto-block when thresholds are hit.

​
Why this matters

Uber burned its entire annual AI budget in 4 months after giving 5,000 engineers Claude Code access. One SaaS team (35 engineers) got a $50,000 April bill from Claude Code, Cursor, and custom agents combined. Budget controls put a hard ceiling on what any agent can spend — per session, per day, or per month.

​
Configure a budget

from polaxis import Polaxis

guard = Polaxis(
    api_key="ag_prod_...",
    agent_id="billing-agent",
    daily_budget_usd=50.00,      # Hard stop at $50/day
    session_budget_usd=5.00,     # Hard stop at $5/session
    alert_at_pct=80,             # Slack alert at 80% of limit
)
Or via the dashboard: Agents → Select agent → Budget tab.

​
Pass estimated cost on each call

result = await guard.evaluate(
    "call_llm",
    {"prompt": "..."},
    estimated_cost_usd=0.05
)

# After the tool runs, record actual cost:
await guard.record_completion(
    tool_name="call_llm",
    actual_cost_usd=0.032,
    duration_ms=1240
)
Polaxis tracks cumulative spend in real time and blocks the next call if the budget is exceeded.

​
What happens when the limit is hit

from polaxis import BlockedError

try:
    result = await guard.evaluate("call_llm", inputs, estimated_cost_usd=0.05)
except BlockedError as e:
    if e.reason == "budget_exceeded":
        print(f"Daily limit reached: {e.details['spent_usd']} / {e.details['limit_usd']}")
The agent raises BlockedError with reason="budget_exceeded". Your code decides whether to fail gracefully, notify the user, or queue for the next day.

​
Budget types

TypeConfig keyResets
Per sessionsession_budget_usdEach new Polaxis() instance
Per daydaily_budget_usdMidnight UTC
Per monthmonthly_budget_usd1st of each month
All three can be set simultaneously. The first limit hit triggers a block.

​
Set budgets via API

PATCH /api/v1/agents/{agent_id}/budget
{
  "daily_budget_usd": 100,
  "session_budget_usd": 10,
  "alert_at_pct": 75
}

​
View spend in the dashboard

Dashboard → Budgets shows:
  • Current spend per agent (today, this month)
  • Spend rate over time
  • Blocked calls due to budget limits
  • Per-tool cost breakdown

​
Soft alerts before the hard stop

Set alert_at_pct to get a Slack notification before the limit is hit: 
guard = Polaxis(
    api_key="ag_prod_...",
    agent_id="research-agent",
    daily_budget_usd=100.00,
    alert_at_pct=80,  # Slack alert at $80 spent
)
The alert gives your team time to intervene before the agent stops cold.