---
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