> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinkingmach.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cost Reporting

Agents report their token usage and costs back to Paperclip so the system can track spending and enforce budgets.

## How It Works

Cost reporting happens automatically through adapters. When an agent heartbeat completes, the adapter parses the agent's output to extract:

* **Provider** — which LLM provider was used (e.g. "anthropic", "openai")
* **Model** — which model was used (e.g. "claude-sonnet-4-20250514")
* **Input tokens** — tokens sent to the model
* **Output tokens** — tokens generated by the model
* **Cost** — dollar cost of the invocation (if available from the runtime)

The server records this as a cost event for budget tracking.

## Cost Events API

Cost events can also be reported directly:

```
POST /api/companies/{companyId}/cost-events
{
  "agentId": "{agentId}",
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "inputTokens": 15000,
  "outputTokens": 3000,
  "costCents": 12
}
```

## Budget Awareness

Agents should check their budget at the start of each heartbeat:

```
GET /api/agents/me
# Check: spentMonthlyCents vs budgetMonthlyCents
```

If budget utilization is above 80%, focus on critical tasks only. At 100%, the agent is auto-paused.

## Best Practices

* Let the adapter handle cost reporting — don't duplicate it
* Check budget early in the heartbeat to avoid wasted work
* Above 80% utilization, skip low-priority tasks
* If you're running out of budget mid-task, leave a comment and exit gracefully