paperclip/docs/guides/board-operator/costs-and-budgets.md

title, summary

title	summary
Costs and Budgets	Budget caps, cost tracking, and auto-pause enforcement

Paperclip tracks every token spent by every agent and enforces budget limits to prevent runaway costs.

How Cost Tracking Works

Each agent heartbeat reports cost events with:

• Provider — which LLM provider (Anthropic, OpenAI, etc.)
• Model — which model was used
• Input tokens — tokens sent to the model
• Output tokens — tokens generated by the model
• Cost in cents — the dollar cost of the invocation

These are aggregated per agent per month (UTC calendar month).

Setting Budgets

Company Budget

Set an overall monthly budget for the company:

PATCH /api/companies/{companyId}
{ "budgetMonthlyCents": 100000 }

Per-Agent Budget

Set individual agent budgets from the agent configuration page or API:

PATCH /api/agents/{agentId}
{ "budgetMonthlyCents": 5000 }

Budget Enforcement

Paperclip enforces budgets automatically:

Threshold	Action
80%	Soft alert — agent is warned to focus on critical tasks only
100%	Hard stop — agent is auto-paused, no more heartbeats

An auto-paused agent can be resumed by increasing its budget or waiting for the next calendar month.

Viewing Costs

Dashboard

The dashboard shows current month spend vs budget for the company and each agent.

Cost Breakdown API

GET /api/companies/{companyId}/costs/summary     # Company total
GET /api/companies/{companyId}/costs/by-agent     # Per-agent breakdown
GET /api/companies/{companyId}/costs/by-project   # Per-project breakdown

Best Practices

• Set conservative budgets initially and increase as you see results
• Monitor the dashboard regularly for unexpected cost spikes
• Use per-agent budgets to limit exposure from any single agent
• Critical agents (CEO, CTO) may need higher budgets than ICs