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

Files

Dotta 09d2ef1a37 fix: restore docs deleted in v0.2.3 release, add Paperclip branding

- Restored docs/ directory that was accidentally deleted by `git add -A`
  in the v0.2.3 release script
- Replaced generic "P" favicon with actual paperclip icon using brand
  primary color (#2563EB)
- Added light/dark logo SVGs for Mintlify navbar (paperclip icon + wordmark)
- Updated docs.json with logo configuration for dark/light mode
- Fixed release.sh to stage only release-related files instead of `git add -A`
  to prevent sweeping unrelated changes into release commits

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-03 15:49:43 -06:00

1.9 KiB

Raw Blame History

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

1.9 KiB Raw Blame History