Setting monthly_budget_usd on each agent, how the server aggregates SUM(amount_usd) from cost_events against the limit before each heartbeat, and the guard query.
Best practices for setting initial budgets, how to raise or lower limits without downtime, and strategies for different organization sizes.
For a new company in development, start conservatively:
UPDATE companies
SET monthly_budget_usd = 15.00
WHERE slug = 'my-company';
-- Per-agent budgets that sum to 80% of company budget
UPDATE agents SET monthly_budget_usd = 5.00 WHERE name = 'Researcher';
UPDATE agents SET monthly_budget_usd = 4.00 WHERE name = 'Writer';
UPDATE agents SET monthly_budget_usd = 3.00 WHERE name = 'Editor';
-- Total agent budgets: $12 < company budget $15 ✓
Leave a 20% buffer between the sum of agent budgets and the company ceiling. This absorbs small overruns before triggering a company-wide pause.
Rule of thumb per model per 1 000 tasks:
| Model | Avg tokens/task | Cost per 1K tasks |
|---|---|---|
| claude-haiku-3-5 | 800 in / 400 out | ~$0.20 |
| claude-sonnet-4-5 | 800 in / 400 out | ~$2.40 + $6.00 = ~$8.40 |
| claude-opus-4-5 | 800 in / 400 out | ~$12 + $30 = ~$42 |
| gpt-4o-mini | 800 in / 400 out | ~$0.36 |
Start with Haiku or GPT-4o-mini for high-volume agents; upgrade to Opus/Sonnet only when quality demands it.
# Via API — no restart needed
curl -X PATCH http://localhost:3100/api/companies/${COMPANY_ID} \
-H "Content-Type: application/json" \
-d '{"monthly_budget_usd": 50.00}'
# Unpause if the company was paused
curl -X PATCH http://localhost:3100/api/companies/${COMPANY_ID} \
-H "Content-Type: application/json" \
-d '{"paused": false}'
Changes take effect on the next heartbeat tick.
Set up a webhook notification when spend reaches 80% of budget:
{
"webhook_url": "https://your-app.com/alerts",
"events": ["budget.warning_80pct", "budget.exceeded"],
"threshold_pct": 80
}
Or implement a scheduled SQL check:
-- Run this query daily; alert if any agent > 80% budget
SELECT name, monthly_budget_usd, spent, ROUND(pct_used) AS pct
FROM (
SELECT a.name, a.monthly_budget_usd,
SUM(ce.cost_usd) AS spent,
100 * SUM(ce.cost_usd) / a.monthly_budget_usd AS pct_used
FROM agents a
JOIN cost_events ce ON ce.agent_id = a.id
AND date_trunc('month', ce.created_at) = date_trunc('month', now())
WHERE a.company_id = 'your-company-id'
GROUP BY a.id, a.name, a.monthly_budget_usd
) t
WHERE pct_used >= 80;
On the 1st of each calendar month:
- All cost_events from the prior month are retained (audit trail)
- MTD spend is recalculated from scratch
- Paused agents automatically un-pause
- Company paused flag is reset if it was triggered only by budget
You can force an early reset in development:
-- Delete this month's cost events (dev only — destroys audit trail)
DELETE FROM cost_events
WHERE company_id = 'your-company-id'
AND date_trunc('month', created_at) = date_trunc('month', now());
-- Unpause
UPDATE companies SET paused = false WHERE id = 'your-company-id';
UPDATE agents SET status = 'active' WHERE company_id = 'your-company-id';