PaperClipAI/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.

Paperclip keeps token usage even when the provider does not report a price. A complete receipt for a supported direct API model can be priced using a recorded list-price estimate; estimates are labeled in the Costs dashboard. Missing costs are never treated as proof of free usage.

Understanding incomplete cost data

The Costs overview shows a compact line such as 12 run costs unavailable when usage is missing a price or final receipt. Expand it with the arrow to see the affected entries, grouped alphabetically by agent with links to each run. Unknown billing types use their own label rather than counting as unavailable costs. Estimates remain labeled on spend cards and tables. Select an agent's name to open its configuration. Provider and biller cards also label estimates and unavailable prices. A total with only unpriced entries shows a dash instead of $0.00. Successful recording shows a confirmation even when it resolves the last gap.

• Billing category unknown: select an AI connection in the agent's configuration for future runs. Recorded charges remain in the inference ledger.
• Model not reported: select an explicit model for future runs. ACP adapters also retain the provider-selected model when the runtime reports it, including its default model. A model change during a turn is not priced as one model.
• Cost unavailable: the past entry has no reliable price. No cleanup is required; totals include known charges only.
• Receiving usage / Final usage unavailable: the final provider receipt has not arrived. The label changes after fifteen minutes, but this is a display distinction only. Paperclip still accepts late receipts and preserves the accounting debt. Rerunning an agent does not recover its previous receipt.
• Ready to record: Paperclip can retry saved accounting data. Retry cost recording records costs only and never starts agent work. Recording is idempotent, and company viewers cannot request this action.

Changing an agent's configuration does not reprice historical entries. Normal credits and fixed billing are listed as other billing usage, without an unknown billing warning. OpenCode API billing can be identified from a nonempty API key for its selected provider; the provider name alone is insufficient evidence. Remote OpenCode runs use only keys forwarded to the remote process. Keys present on the Paperclip server do not establish a remote run's billing category.

Board cost readers can inspect bounded details at GET /api/companies/{companyId}/costs/data-quality, with the same date bounds as other cost reports. Details contain no provider errors or credentials and load only when expanded in the UI. Authorized board members can request recording at POST /api/companies/{companyId}/costs/retry-accounting with { "runId": "uuid" }.

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