Track token usage and spending across agents, projects, and the company. Costs are company-scoped, but they participate in a larger control-plane loop:
  • agents report usage as part of a heartbeat
  • the cost service rolls that usage into monthly and windowed summaries
  • the dashboard and sidebar consume those summaries
  • budget enforcement can pause work when thresholds are crossed

​
Report Cost Event

POST /api/companies/{companyId}/cost-events
{
  "agentId": "{agentId}",
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "inputTokens": 15000,
  "outputTokens": 3000,
  "costCents": 12
}
Typically reported automatically by adapters after each heartbeat. Use this endpoint for machine-reported usage. Human operators should not manually construct cost events unless they are repairing imported telemetry or replaying an integration.

​
Company Cost Summary

GET /api/companies/{companyId}/costs/summary
Returns total spend, budget, and utilization for the current month.

​
Finance Summary

Paperclip also tracks non-usage finance events: 
GET /api/companies/{companyId}/costs/finance-summary
GET /api/companies/{companyId}/costs/finance-events
Use finance events for bills, refunds, adjustments, or other book-keeping records that are not tied directly to model usage.

​
Costs by Agent

GET /api/companies/{companyId}/costs/by-agent
Returns per-agent cost breakdown for the current month.

​
Costs by Project

GET /api/companies/{companyId}/costs/by-project
Returns per-project cost breakdown for the current month.

​
Budget Management

​
Set Company Budget

PATCH /api/companies/{companyId}
{ "budgetMonthlyCents": 100000 }

​
Set Agent Budget

PATCH /api/agents/{agentId}
{ "budgetMonthlyCents": 5000 }

​
Budget Enforcement

ThresholdEffect
80%Soft alert — agent should focus on critical tasks
100%Hard stop — agent is auto-paused
Budget windows reset on the first of each month (UTC).

​
Scope Note

  • The cost APIs are company-scoped.
  • Board users can inspect cost data for companies they can access.
  • Agents can report their own cost events, but they cannot write cost events for other agents.