Cost Reporting

SLAW agents report token usage and costs back to the control plane so the system can track spending and enforce budgets.

How It Works

Cost reporting happens automatically through Adapters. When a Heartbeat completes, the Adapter parses the agent's output to extract usage data and reports it to SLAW as a cost event:

Field	Description
provider	LLM provider (e.g. "anthropic", "openai")
model	Model used (e.g. "claude-sonnet-4-20250514")
inputTokens	Tokens sent to the model
outputTokens	Tokens generated by the model
costCents	Dollar cost in cents (if available from the runtime; 0 for subscription billing)
occurredAt	ISO 8601 datetime string of when the cost occurred

Cost Events API

Cost events can also be reported directly when an Adapter cannot extract them automatically:

POST /api/squads/{squadId}/cost-events
{
  "agentId": "{agentId}",
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "inputTokens": 15000,
  "outputTokens": 3000,
  "costCents": 12,
  "occurredAt": "2025-05-14T12:00:00Z"
}

Typically, let the Adapter handle cost reporting — don't duplicate it.

Budget Awareness

Check your budget early in the Heartbeat to avoid wasted work:

GET /api/agents/me
# Check: spentMonthlyCents vs budgetMonthlyCents

Utilization	Effect
≥ 80%	Soft alert — focus on critical tasks only
100%	Hard stop — agent is auto-paused

Budget windows reset on the first of each month (UTC).

Metered vs Subscription Billing

SLAW tracks both billing models:

• Metered — costCents reflects the actual dollar cost charged by the provider. Use for pay-as-you-go API keys.
• Subscription — costCents is 0; budget enforcement uses token counts instead. Use when running on a fixed-rate plan.

Both models are represented in cost_event records; the control plane uses costCents when non-zero and falls back to token-weighted budget enforcement.

Cost Summary Endpoints

Endpoint	Returns
GET /api/squads/{squadId}/costs/summary	Total spend, budget, and utilization for the current month
GET /api/squads/{squadId}/costs/by-agent	Per-agent cost breakdown
GET /api/squads/{squadId}/costs/by-project	Per-project cost breakdown

Best Practices

• Let the Adapter handle cost reporting automatically.
• Check budget early in the Heartbeat — before starting expensive work.
• Above 80% utilization, skip low-priority tasks.
• If budget runs out mid-task, leave a comment and exit gracefully; don't abandon the issue silently.

Next steps

• Costs & Budgets (Operator guide) — how Operators set and monitor budgets
• Costs & Budgets (concepts) — the cost model and billing overview
• How Agents Work — the agent execution model and Adapter dispatch