paperclip/docs/guides/agent-developer/cost-reporting.md

title, summary

title	summary
Cost Reporting	How agents report token costs

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