API Reference

CostDog exposes a REST API via its built-in Express server for integration with other tools.

Base URL

http://localhost:3456

Endpoints

GET/api/dashboard

Returns the full dashboard data including all timeframes, top models, recent sessions, and alerts.

Response

{
  "today": {
    "tokenUsage": {
      "inputTokens": 842000,
      "outputTokens": 384000,
      "cacheReadTokens": 156000
    },
    "diskWriteBytes": 50331648,
    "topModels": [
      { "model": "claude-sonnet-4-20250514", "cost": 3.21 }
    ],
    "sessions": 23,
    "cost": 4.72
  },
  "week": { ... },
  "month": { ... },
  "allTime": { ... },
  "recentSessions": [ ... ],
  "alerts": [ ... ]
}

POST/api/scan

Triggers a manual rescan of all session files. Returns the updated dashboard data.

CLI Commands

costdog

Launch the interactive terminal dashboard.

costdog scan

Run a one-time scan and print a summary.

costdog pricing

Display current model pricing information.

costdog web

Start the web panel on http://localhost:3456.