71 lines
1.9 KiB
Markdown
71 lines
1.9 KiB
Markdown
---
|
|
title: Costs and Budgets
|
|
summary: 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
|