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
  }
}

Budgets

Named budgets track spend against a daily, weekly, or monthly limit and fire alerts at configurable percentage thresholds. Daily budgets can additionally auto-stop executions once the limit is reached. All budget endpoints are under /api/v1/admin/costs/ and require organization context.

List Budgets


GET /api/v1/admin/costs/budgets

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	1-indexed page number
`page_size`	integer	`25`	Items per page (max 200)

Response (200):


{
  "budgets": [
    {
      "id": "budget_a1b2c3d4e5f6",
      "name": "Monthly Platform Budget",
      "type": "monthly",
      "limit": 400.00,
      "current": 184.00,
      "alerts": [
        { "threshold": 50, "channels": ["email"], "triggered": true, "triggered_at": "2026-02-14T09:00:00Z" },
        { "threshold": 80, "channels": ["email", "slack"], "triggered": false, "triggered_at": null },
        { "threshold": 100, "channels": ["email", "webhook"], "triggered": false, "triggered_at": null }
      ],
      "auto_stop": false,
      "created_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-02-14T09:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 25,
  "total_count": 1,
  "has_more": false
}

Create a Budget


POST /api/v1/admin/costs/budgets

Request:


{
  "name": "Monthly Platform Budget",
  "type": "monthly",
  "limit": 400.00,
  "alerts": [
    { "threshold": 50, "channels": ["email"] },
    { "threshold": 80, "channels": ["email", "slack"] },
    { "threshold": 100, "channels": ["email", "webhook"] }
  ],
  "auto_stop": false
}

Field	Type	Required	Description
`name`	string	Yes	Human-readable budget name (1–120 chars)
`type`	string	No	Budget window: `daily`, `weekly`, or `monthly` (default `monthly`)
`limit`	number	Yes	Spend limit in USD (must be greater than 0)
`alerts`	array	No	Percentage-threshold alerts (`threshold` 0–100, `channels` from `email`/`slack`/`webhook`)
`auto_stop`	boolean	No	Stop executions when the limit is exceeded (daily budgets only)

Response (200): the created BudgetResponse (same shape as the list items above, with a server-assigned id and a current spend estimate).

Update a Budget


PUT /api/v1/admin/costs/budgets/{budget_id}

All fields are optional; only the fields you send are changed.


{
  "limit": 500.00,
  "alerts": [
    { "threshold": 50, "channels": ["email"] },
    { "threshold": 90, "channels": ["email", "slack"] }
  ]
}

Response (200): the updated BudgetResponse.

Delete a Budget


DELETE /api/v1/admin/costs/budgets/{budget_id}

Response (204): No content.

Alert Behavior

Setting	Behavior
`channels`	Where a triggered alert is delivered: `email`, `slack`, or `webhook`
`triggered` / `triggered_at`	Set automatically when spend crosses the threshold; reset when spend falls back below it
`auto_stop`	When `true` on a `daily` budget, executions are stopped once the daily limit is reached