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 monthly spending caps per agent:

• monthlyBudget: maximum estimated cost per calendar month
• budgetAction:
  • warn
  • block

Budget usage resets at the start of each calendar month and is tracked automatically from usage records.

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.