Cost Tracking

SwarmClaw tracks token usage and estimated costs for model calls, then aggregates them into the Usage surface and API summaries.

How It Works

Each successful provider completion records:

• input, output, and total tokens
• estimated cost
• provider and model
• chat or session timestamp
• extension token metadata when extensions are active

These records are stored and rolled up by provider, agent, extension, and time window.

Usage API

Retrieve usage data via the REST API:

GET /api/usage

Query Parameters

Response

{
  "totalTokens": 1590000,
  "totalCost": 12.45,
  "byAgent": {
    "main-wayde": { "tokens": 620000, "cost": 4.32 }
  },
  "byProvider": {
    "openai": { "tokens": 970000, "cost": 8.75 }
  },
  "byExtension": {
    "tool-logger.js": {
      "definitionTokens": 3200,
      "invocationTokens": 18200,
      "invocations": 74,
      "estimatedCost": 0.1187
    }
  },
  "timeSeries": [
    { "bucket": "2026-03-01T14", "tokens": 28000, "cost": 0.23 }
  ]
}

Notes

• timeSeries.bucket is hourly for 24h and daily for 7d and 30d.
• providerHealth is derived from usage records currently stored by the app.
• extension cost is estimated from aggregate cost-per-token across the selected range.

Usage Surface

The Usage page rolls these records up into:

• provider cost breakdown
• token usage over time
• per-agent cost tracking
• provider health and latency summaries
• task throughput context alongside usage

Usage Badge

The chat header includes a usage badge that updates after each completion with token and cost totals for the active chat.

Agent Budget Limits

You can set spending caps per agent across three rolling windows:

• monthlyBudget — maximum estimated cost per calendar month
• dailyBudget — maximum estimated cost per UTC day
• hourlyBudget — maximum estimated cost per trailing 60 minutes
• budgetAction:
  • warn (default) — turn proceeds; UI surfaces a budget warning
  • block — turn is denied at enqueue for autonomous runs (heartbeats, missions, scheduler) and during chat-turn preparation for any run

Budget windows are tracked via push-based rollup (spentMonthlyCents, spentDailyCents, spentHourlyCents, lastSpendRollupAt) so the check is O(1) instead of scanning every usage record. Daily windows reset at UTC midnight, monthly at UTC month boundary, hourly as a rolling 60-minute window.

User-initiated chats always flow through even when an agent is over budget — only autonomous activity is hard-stopped. This protects users who want to talk to an agent that's hit its cap.

Billing Codes

Tag missions, tasks, and sessions with billingCodes: string[] to roll up cost across multiple agents and runs. Codes are resolved at usage-write time as session.billingCodes ∪ session.mission.billingCodes and stamped onto the usage record.

Query rollups:

GET /api/usage/by-code?codes=client-a,project-x&range=7d

The response groups usage by code and reports per-agent breakdowns inside each code bucket. Omit the codes query param to see all observed codes and their totals.

CLI equivalent:

swarmclaw cost-attribution by-code --query codes=client-a,range=30d

Live Per-Session Usage

For UIs and operators that want a cheap poll without scanning the full aggregate, use the live endpoint:

GET /api/usage/live?sessionId=<id>

Returns a compact per-session snapshot:

{
  "sessionId": "abc",
  "records": 12,
  "totalTokens": 18250,
  "inputTokens": 11100,
  "outputTokens": 7150,
  "estimatedCost": 0.4267,
  "firstAt": 1742140800000,
  "lastAt": 1742144400000,
  "wallclockMs": 3600000,
  "turns": 12
}

Omitting sessionId returns the ten most recently active sessions. CLI equivalent:

swarmclaw usage live --query sessionId=abc

Cost Estimation

Costs are estimated using built-in pricing tables for known providers. For custom providers and some local runtimes, cost may be reported as $0 unless you configure custom pricing in provider settings.