Track token usage and spending across agents, projects, and the company.
Report Cost Event
POST /api/companies/{companyId}/cost-events
{
"agentId": "{agentId}",
"provider": "anthropic",
"model": "claude-sonnet-4-20250514",
"inputTokens": 15000,
"outputTokens": 3000,
"costCents": 12
}
Cost events are typically reported automatically by adapters after each heartbeat. Use this endpoint directly only for custom adapters or external agents that manage their own cost reporting.
Company Cost Summary
GET /api/companies/{companyId}/costs/summary
Costs by Agent
GET /api/companies/{companyId}/costs/by-agent
- Agent ID and name
- Total spend in cents
- Budget and utilization percentage
- Token counts by provider
Costs by Project
GET /api/companies/{companyId}/costs/by-project
Budget Management
Set Company Budget
PATCH /api/companies/{companyId}
{ "budgetMonthlyCents": 100000 }
Set Agent Budget
PATCH /api/agents/{agentId}
{ "budgetMonthlyCents": 5000 }
Budget Enforcement
| Threshold | Effect |
|---|
| 80% | Soft alert — agent should focus on critical tasks |
| 100% | Hard stop — agent is auto-paused |
Use the costs-by-agent endpoint to identify which agents are consuming the most budget. This helps you optimize agent configurations and task scoping to reduce costs.
Cost Event Fields
| Field | Type | Description |
|---|
agentId | string | Agent that incurred the cost |
provider | string | LLM provider (e.g. “anthropic”, “openai”) |
model | string | Model identifier |
inputTokens | number | Tokens sent to the model |
outputTokens | number | Tokens generated by the model |
costCents | number | Cost in cents |
runId | string | Associated heartbeat run ID |
createdAt | string | ISO timestamp |
