Cost & Metrics API

The Cost & Metrics API provides programmatic access to cost analysis, budget tracking, optimization recommendations, and workforce ROI data. Use it to build internal dashboards, generate client-facing reports, or feed data into your analytics stack.

Cost Analysis

GET /api/cost-analysis/summary 🔒 Auth required

Get a combined cost overview across your entire workspace.

Response

{
  "tokenCost": {
    "total": 142.80,
    "byProvider": [
      { "provider": "anthropic", "cost": 98.40 },
      { "provider": "openai", "cost": 44.40 }
    ],
    "byModel": [
      { "model": "claude-haiku-3.5", "cost": 62.10 },
      { "model": "claude-sonnet-4-20250514", "cost": 36.30 }
    ]
  },
  "totalSpend": 142.80,
  "budget": {
    "total": 500.00,
    "utilization": 0.286
  },
  "agentCount": 6,
  "providerCount": 2
}

GET /api/cost-analysis/by-provider 🔒 Auth required

Cost breakdown grouped by AI provider.

Response

{
  "providers": [
    {
      "providerId": "anthropic",
      "providerName": "Anthropic",
      "totalCost": 98.40,
      "totalTokens": 12400000,
      "models": ["claude-haiku-3.5", "claude-sonnet-4-20250514"]
    }
  ]
}

GET /api/cost-analysis/by-model 🔒 Auth required

Cost breakdown grouped by model, with per-model token economics.

Response

{
  "models": [
    {
      "model": "claude-haiku-3.5",
      "provider": "anthropic",
      "inputCost": 18.40,
      "outputCost": 43.70,
      "totalCost": 62.10,
      "inputTokens": 23000000,
      "outputTokens": 10925000,
      "pctOfTotal": 43.5
    }
  ]
}

GET /api/cost-analysis/agents 🔒 Auth required

Per-agent cost breakdown with budget utilization.

Response

{
  "agents": [
    {
      "id": "550e8400-...",
      "name": "Nova",
      "modelName": "claude-haiku-3.5",
      "actualCost": 28.40,
      "budget": 100.00,
      "utilization": 0.284,
      "overBudget": false,
      "status": "online"
    }
  ]
}

GET /api/cost-analysis/recommendations 🔒 Auth required

Model optimization recommendations with estimated monthly savings.

The platform analyzes your agents’ task types and usage patterns to recommend model downgrades where quality would be maintained at lower cost.

Response

{
  "recommendations": [
    {
      "agentId": "550e8400-...",
      "agentName": "Pulse",
      "currentModel": "claude-sonnet-4-20250514",
      "recommendedModel": "claude-haiku-3.5",
      "savingsPct": 73.3,
      "estimatedMonthlySavings": 48.20,
      "currentInputPrice": 3.00,
      "recommendedInputPrice": 0.80
    }
  ],
  "totalPotentialSavings": 48.20
}

GET /api/cost-analysis/budget-alerts 🔒 Auth required

List agents that have exceeded their monthly cost budget.

Response

{
  "alertCount": 2,
  "alerts": [
    {
      "agentId": "550e8400-...",
      "agentName": "Atlas",
      "modelName": "claude-sonnet-4-20250514",
      "actualCost": 124.80,
      "budget": 100.00,
      "overage": 24.80,
      "overagePct": 24.8
    }
  ]
}

GET /api/cost-analysis/pricing 🔒 Auth required

Retrieve the current model pricing catalog.

Returns all supported models with their per-token pricing. Use this to calculate cost estimates before deploying agents.

Response

{
  "models": [
    {
      "id": "claude-haiku-3.5",
      "provider": "anthropic",
      "category": "economy",
      "inputPricePerMillion": 0.80,
      "outputPricePerMillion": 4.00
    },
    {
      "id": "claude-sonnet-4-20250514",
      "provider": "anthropic",
      "category": "flagship",
      "inputPricePerMillion": 3.00,
      "outputPricePerMillion": 15.00
    }
  ]
}

Workforce ROI

These endpoints power the Workforce dashboard and quantify the ROI of your agent fleet relative to human labor equivalents.

GET /api/agents/workforce/summary 🔒 Auth required

Fleet-wide ROI summary — agents deployed, cost vs. human equivalent, hours saved.

Response

{
  "total_agents": 6,
  "active_agents": 5,
  "paused_agents": 1,
  "draft_agents": 0,
  "total_human_salary": 360000,
  "total_agent_cost_monthly": 284.40,
  "total_budget_monthly": 600.00,
  "total_hours_saved_monthly": 480,
  "total_tasks_completed": 1842,
  "total_invocations": 3210,
  "total_errors": 18,
  "monthly_human_equivalent": 30000,
  "monthly_savings": 29715.60,
  "roi_percent": 10449.0,
  "departments": [
    {
      "department": "Operations",
      "agent_count": 3,
      "monthly_savings": 18200.00
    }
  ]
}

GET /api/agents/workforce/agents 🔒 Auth required

Per-agent ROI metrics — cost, tasks completed, hours saved, and return on investment.

Response (per agent)

[
  {
    "id": "550e8400-...",
    "name": "Nova",
    "status": "online",
    "category": "Research",
    "department": "Strategy",
    "role_title": "Research Analyst",
    "model_provider": "anthropic",
    "model_name": "claude-haiku-3.5",
    "human_equivalent_salary": 75000,
    "estimated_hours_saved": 80,
    "actual_cost_monthly": 28.40,
    "cost_budget_monthly": 100.00,
    "tasks_completed": 312,
    "invocation_count": 540,
    "error_count": 3,
    "avg_response_ms": 3840,
    "monthly_human_equivalent": 6250,
    "monthly_savings": 6221.60,
    "roi_percent": 21906.3,
    "cost_per_task": 0.091
  }
]

GET /api/agents/workforce/trends 🔒 Auth required

Month-over-month trend data for the full fleet.

Query parameters

Parameter	Type	Description
`months`	integer	Number of months of history to return (default: 6)

Response

{
  "months": 6,
  "trends": [
    {
      "period": "2026-03",
      "tasks_completed": 1842,
      "invocations": 3210,
      "total_tokens": 48200000,
      "total_cost": 284.40,
      "errors": 18,
      "avg_response_ms": 3840,
      "active_agents": 5
    }
  ]
}

Activity Log

GET /api/activity 🔒 Auth required

Query the agent activity log — tool calls, session events, cron executions, and config changes.

Use this endpoint to stream events into a SIEM, build compliance exports, or feed operational dashboards.

Query parameters

Parameter	Type	Description
`agentId`	string	Filter to a specific agent
`eventType`	string	Filter by event type
`from`	ISO 8601 datetime	Start timestamp (inclusive)
`to`	ISO 8601 datetime	End timestamp (inclusive)
`limit`	integer	Results per page (default: 100, max: 500)
`offset`	integer	Pagination offset

Response

{
  "data": [
    {
      "id": "evt-uuid-...",
      "eventType": "tool_call",
      "agentId": "550e8400-...",
      "agentName": "Nova",
      "details": {
        "tool": "web_search",
        "success": true,
        "durationMs": 1240
      },
      "createdAt": "2026-03-17T08:01:44Z"
    }
  ],
  "pagination": {
    "total": 1842,
    "limit": 100,
    "offset": 0,
    "hasMore": true
  }
}