Costs API

The Costs API provides real-time visibility into LLM spending across agents, providers, and pipeline runs. All cost endpoints are part of the B2B API and require organization context.

Cost Metrics

Retrieve comprehensive cost optimization metrics for your organization.


GET /api/v1/admin/metrics/cost-optimization

Headers:


Authorization: Bearer {token}
X-Org-ID: {organization_id}

Query Parameters:

Parameter	Type	Default	Description
`period`	string	`7d`	Time period (`24h`, `7d`, `30d`, `90d`)
`granularity`	string	`daily`	Time series granularity (`hourly`, `daily`, `weekly`)

Response (200):


{
  "period": "7d",
  "total_cost": 42.87,
  "by_provider": {
    "openai": { "cost": 22.50, "requests": 8400, "avg_cost_per_request": 0.00268 },
    "google": { "cost": 12.30, "requests": 5200, "avg_cost_per_request": 0.00237 },
    "deepseek": { "cost": 5.12, "requests": 6800, "avg_cost_per_request": 0.00075 },
    "anthropic": { "cost": 2.95, "requests": 1100, "avg_cost_per_request": 0.00268 }
  },
  "by_agent": {
    "extractor_agent": { "cost": 12.30, "executions": 5200, "avg_latency_ms": 1240 },
    "analyzer_agent": { "cost": 15.40, "executions": 4800, "avg_latency_ms": 980 },
    "validator_agent": { "cost": 5.12, "executions": 4600, "avg_latency_ms": 620 },
    "reporter_agent": { "cost": 7.10, "executions": 3900, "avg_latency_ms": 450 },
    "summarizer_agent": { "cost": 2.95, "executions": 1100, "avg_latency_ms": 2100 }
  },
  "time_series": [
    { "date": "2026-02-01", "cost": 5.42, "requests": 3200 },
    { "date": "2026-02-02", "cost": 6.18, "requests": 3800 },
    { "date": "2026-02-03", "cost": 5.90, "requests": 3600 },
    { "date": "2026-02-04", "cost": 7.21, "requests": 4200 },
    { "date": "2026-02-05", "cost": 6.45, "requests": 3900 },
    { "date": "2026-02-06", "cost": 5.89, "requests": 3500 },
    { "date": "2026-02-07", "cost": 5.82, "requests": 3400 }
  ],
  "projections": {
    "monthly_estimate": 184.00,
    "trend": "stable",
    "budget_utilization": 0.46
  }
}

Response Fields

Field	Description
`total_cost`	Aggregate cost in USD for the selected period
`by_provider`	Cost breakdown grouped by LLM provider
`by_agent`	Cost breakdown grouped by agent name
`time_series`	Cost data points at the requested granularity
`projections.monthly_estimate`	Projected monthly cost based on current usage
`projections.trend`	Cost trend direction (`increasing`, `stable`, `decreasing`)
`projections.budget_utilization`	Percentage of monthly budget consumed

Health Endpoint (Daily Cost Summary)

The health endpoint includes a summary of daily cost data.


GET /api/v1/health

Response (200):


{
  "status": "healthy",
  "version": "1.4.2",
  "uptime_seconds": 86400,
  "daily_cost": {
    "total": 6.45,
    "budget_limit": 50.00,
    "utilization": 0.129,
    "top_agent": "analyzer_agent",
    "top_agent_cost": 2.10
  }
}

Budget Thresholds

Configure cost alerts and automatic throttling when spend exceeds defined thresholds.

Get Budget Configuration


GET /api/v1/admin/budget

Response (200):


{
  "monthly_budget": 400.00,
  "daily_limit": 50.00,
  "alert_thresholds": [
    { "percent": 50, "action": "notify" },
    { "percent": 80, "action": "notify" },
    { "percent": 95, "action": "throttle" },
    { "percent": 100, "action": "block" }
  ],
  "notification_channels": ["email", "webhook"],
  "current_month_spend": 184.00,
  "current_day_spend": 6.45
}

Update Budget Configuration


PUT /api/v1/admin/budget

Request:


{
  "monthly_budget": 500.00,
  "daily_limit": 75.00,
  "alert_thresholds": [
    { "percent": 50, "action": "notify" },
    { "percent": 80, "action": "notify" },
    { "percent": 100, "action": "throttle" }
  ]
}

Threshold Actions

Action	Behavior
`notify`	Send an alert to configured notification channels
`throttle`	Reduce request rate by deprioritizing non-critical agents
`block`	Reject new requests until the next billing period