paperclip_report_cost_event
Record LLM token usage and cost for an agent to enable budget tracking and spend analytics. Logs input/output tokens, provider, model, and timestamp.
Instructions
Report an agent's token usage and cost event to Paperclip for budget tracking.
Args:
agentId: string — ID of the agent that incurred the cost (example: "agt_abc123")
provider: string — LLM provider name (example: "anthropic")
model: string — Model identifier (example: "claude-sonnet-4-6")
inputTokens: integer — Number of input tokens consumed
outputTokens: integer — Number of output tokens generated
costCents: number — Total cost in cents (non-negative)
occurredAt: string — ISO 8601 timestamp (example: "2026-04-16T12:00:00.000Z")
Returns: Returns the created cost event record: id, agentId, provider, model, costCents, occurredAt.
Examples:
Use when: recording a completed LLM API call for spend analytics and budget enforcement
Don't use when: you want a cost summary — use paperclip_get_cost_summary or paperclip_get_costs_by_agent
Error Handling:
400: validation failure → check costCents ≥ 0, occurredAt is valid ISO 8601, tokens are integers
401: authentication failed → check PAPERCLIP_API_KEY
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agentId | Yes | ID of the agent that incurred the cost | |
| provider | Yes | LLM provider name (e.g. anthropic, openai) | |
| model | Yes | Model name (e.g. claude-sonnet-4-6) | |
| inputTokens | Yes | Number of input tokens consumed | |
| outputTokens | Yes | Number of output tokens generated | |
| costCents | Yes | Total cost in cents | |
| occurredAt | Yes | ISO 8601 timestamp of when the cost was incurred |