Budget & Cost Control¶

SynthOrg tracks every LLM API call and enforces spending limits at multiple levels. This guide covers how to configure budgets, set alert thresholds, handle provider quota exhaustion, and monitor spending.

Budget Architecture¶

Budgets are enforced in a three-layer hierarchy:

graph TD
    Company["Company Budget<br/><small>total_monthly: 200 USD</small>"]
    Eng["Engineering<br/><small>60% = 120 USD</small>"]
    Prod["Product<br/><small>20% = 40 USD</small>"]
    Exec["Executive<br/><small>20% = 40 USD</small>"]
    Dev1["Developer A<br/><small>daily: 25 USD</small>"]
    Dev2["Developer B<br/><small>daily: 25 USD</small>"]
    PM["Product Manager<br/><small>daily: 25 USD</small>"]

    Company --> Eng
    Company --> Prod
    Company --> Exec
    Eng --> Dev1
    Eng --> Dev2
    Prod --> PM

The budget enforcer checks spending at two boundaries:

1. Pre-flight: before a task is assigned, verify sufficient budget remains
2. In-flight: monitor spending during task execution (approximate under concurrency)

Both refuse spend. Neither moves an agent onto a different model: an agent's (provider, model) pair is your choice about where its work runs and what it costs, and nothing in the loop rewrites it. Cost discipline comes from selection instead, which prefers the cheapest agent at the rung each piece of work demands (see Keeping costs down).

Configuring the Budget¶

budget:
  total_monthly: 200.0
  currency: "USD"
  reset_day: 1
  per_task_limit: 10.0
  per_agent_daily_limit: 25.0

Budget Fields¶

Alert Thresholds¶

Alert thresholds trigger notifications and behaviour changes as spending approaches the budget limit:

budget:
  alerts:
    warn_at: 75
    critical_at: 90
    hard_stop_at: 100

What happens at each level:

Keeping costs down¶

There is no automatic model downgrade, and this is deliberate. An agent is a fixed unit of role, personality and model: the pair you bind is your decision about where its work runs and what it costs, and a run whose model was swapped out underneath it would report a capability rung that meant nothing and bill a connection you did not choose.

What keeps the bill down instead is who takes the work:

• Each task's stakes and complexity set the capability rung it needs. The selection ladder prefers an agent at exactly that rung over a stronger one, so an idle expert agent does not pick up routine work simply because it is free. This applies to every assignment, not only once a threshold is crossed.
• Tune the rungs to your appetite with the engine.capability_floor_low, engine.capability_floor_normal, engine.capability_floor_high and engine.capability_floor_critical settings. They take effect on the next assignment, with no restart.
• Dial reasoning depth per stakes level with engine.reasoning_effort_*. This is the one lever that changes the call itself rather than who makes it, which is why the cost_disciplined posture uses it.
• Staff a mix of rungs. A roster with only expert agents pays expert rates for routine work, because there is no cheaper agent for the ladder to prefer.

When the money genuinely runs out, the hard stops above refuse the work, which is an outcome you can see and act on.

Cost Tracking¶

Every LLM API call is recorded as a cost record with full context:

When money measures nothing¶

A connection that bills by flat subscription records cost = 0.0 on every call. That is the correct number: there is no per-1000-token price to attribute. The consequence is that a money ceiling cannot bind such a run at all, and a budget percentage read over it says the budget is untouched while work is happening continuously.

Set billing_model on each provider connection so the system can tell the two zeroes apart. Where it cannot measure, every money surface says so rather than reporting headroom: the budget page shows a notice instead of a percentage, the receipt marks its total, the Prometheus percentage ships alongside synthorg_budget_spend_measurability, and hiring is held rather than waved through on an unmeasured zero. Setting a positive money ceiling while every configured connection is unmeasurable is refused at write time, naming the bound that does apply; the refusal covers both the global budget.run_hard_ceiling and a task's own hard_ceiling.

A window is judged on the rows in it, so there are three verdicts and not two. measured means every record in the window was metered, and it is the only verdict that carries a percentage. unmeasurable means none were. mixed means some were, and it has no percentage either: the metered rows are real, but the flat-rate ones contributed nothing to the total, so the ratio understates by an unknown amount and reads as headroom. SpendingSummary.budget_used_percent is therefore None on both, and a consumer suppresses the figure and shows the verdict instead. Every surface answers the same way: the budget page and the receipt name the state, synthorg_budget_spend_measurability and its daily sibling publish it as a state set with exactly one series at 1 while the percentage gauges stay at zero, and hiring reads the verdict before spending.

Runaway backstops¶

Two ceilings stop a single run consuming without limit. Both ship on, and both apply without a restart.

Reaching or exceeding either run ceiling parks the run rather than failing it: the checker halts at >=, not past it, so a run whose usage lands exactly on its ceiling is already parked. An approval is raised naming the unit, the ceiling, and the usage. Resume by raising the bound that halted it above the usage the approval reports and releasing the parked approval; the rebuilt checker reads the new value, and a replacement equal to the usage halts again on the next check. Each unit has its own bound and the checker resolves them separately, so raising the other one resumes nothing: a money halt needs budget.run_hard_ceiling or that task's own hard_ceiling, a token halt needs budget.run_hard_token_ceiling or its hard_token_ceiling, and either per-task field is written with PATCH /api/v1/tasks/{id}.

POST /api/v1/budget/forecasts/{id}/raise_ceiling is a different lever. It records a new ceiling on the forecast row and clears the dashboard halt banner, which is a read-side marker; enforcement still reads the task field or the setting, so a run resumed on that call alone halts again at the next check.

Both paths above are shown with the shipped default api_prefix of /api/v1. That prefix is configurable, so a deployment that changed it serves the same routes beneath its own.

API Endpoints¶

Spending Reports¶

The budget system provides two aggregation views:

• Daily summary: spending per agent and model for a given day
• Period summary: spending over a date range with trend data

These are available via the dashboard budget page and the REST API.

Department Budget Allocation¶

Each department receives a percentage of the company budget via budget_percent:

departments:
  - name: "engineering"
    budget_percent: 60    # 60% of total_monthly
  - name: "product"
    budget_percent: 20
  - name: "executive"
    budget_percent: 20

Department budgets are advisory; the hard enforcement is at the company and per-agent levels. Department allocation helps with reporting and planning.

Practical Example¶

Here is a complete budget configuration for a startup team staffed across three capability rungs:

budget:
  total_monthly: 150.0
  currency: "USD"
  reset_day: 1
  per_task_limit: 8.0
  per_agent_daily_limit: 20.0
  alerts:
    warn_at: 70
    critical_at: 85
    hard_stop_at: 95

Scenario walkthrough:

1. Day 1-15: Normal operation. Routine low-stakes work goes to the basic-bound agents because they match its rung exactly, so the expert-bound architect is only paid for the work that needs it.
2. Day 16: Spending reaches 70% (105 USD). A warning alert is emitted, and the budget page shows the trend.
3. Day 18: You decide to tighten up. Raising engine.capability_floor_normal would send more work to expensive agents, so instead you dial engine.reasoning_effort_normal down a notch and let the ladder keep doing its job. The change applies to the next assignment, with no restart.
4. Day 22: Spending reaches 85% (127.50 USD). Critical alert emitted.
5. Day 25: Spending reaches 95% (142.50 USD). Hard stop: new tasks are rejected until the budget resets on Day 1.

Budget API¶

Query spending, stream cost records, and integrate budget alerts into external dashboards.

Budget configuration¶

curl http://localhost:3001/api/v1/budget/config \
  -H "Cookie: ${SESSION}" | jq

Returns the active BudgetConfig (limits, alert thresholds, cascade rules, currency). Current period spending and alert level are derived from the cost records stream (/budget/records summaries) or the WebSocket budget channel; there is no separate /budget/status endpoint today.

List cost records¶

# First page, 100 records (server default is 50 when limit is omitted)
curl "http://localhost:3001/api/v1/budget/records?limit=100" \
  -H "Cookie: ${SESSION}" | jq

# Filter by agent
curl "http://localhost:3001/api/v1/budget/records?agent_id=${AGENT_ID}&limit=50" \
  -H "Cookie: ${SESSION}" | jq

# Filter by task
curl "http://localhost:3001/api/v1/budget/records?task_id=${TASK_ID}" \
  -H "Cookie: ${SESSION}" | jq

The response includes data (paginated records), daily_summary (per-day totals aggregated across ALL matching records, not just the page), and period_summary (overall totals + computed avg_cost).

Supported query parameters: agent_id, task_id, offset, limit. Additional slicing (by provider, model, tag, project, date range) is done client-side from the paginated response. A dedicated report-generation endpoint with server-side slicing is tracked on the GitHub issue tracker.

Budget alert webhook integration¶

Budget thresholds emit notifications through NotificationDispatcher. To route them to a configured sink (see Notifications & Events for the shipped adapter catalog), add the sink to notifications.sinks and filter by event_type starting with BUDGET_.

Alternatively, subscribe to the budget WebSocket channel for real-time threshold events:

ws.send(JSON.stringify({ action: 'subscribe', channels: ['budget'] }))

Wire event types (see WsEventType in src/synthorg/api/ws_models.py): budget.record_added, budget.alert.

Risk budget enforcement¶

Risk enforcement (risk_budget.enabled: true) is handled internally by RiskTracker and RiskEnforcer. It is not exposed through dedicated public API endpoints today; risk events flow through the same budget.alert WebSocket event type described above.

See Also¶

• Company Configuration: full configuration reference
• Agent Roles & Hierarchy: per-agent model assignment
• Design: Budget & Cost: budget architecture in the design spec
• Notifications & Events: budget alert routing