The costs resource is read-mostly. You ask it for roll-ups at a scope (company, team, agent, project, task, or run) and it returns spend in USD and in tokens, plus a breakdown by category. Writes to the cost table come from the orchestrator, not from the API. You cannot POST a cost entry; the orchestrator captures them automatically. You can, however, correct or annotate a cost entry via the admin endpoints if you have the scope for it.

​
Endpoints

MethodPathPurpose
GET/v1/companies/{cid}/costsCompany-level roll-up
GET/v1/companies/{cid}/costs/teams/{tid}Team-level roll-up
GET/v1/companies/{cid}/costs/agents/{aid}Agent-level roll-up
GET/v1/companies/{cid}/costs/projects/{pid}Project-level roll-up
GET/v1/companies/{cid}/costs/issues/{iid}Task-level roll-up
GET/v1/companies/{cid}/costs/runs/{rid}Run-level detail
GET/v1/companies/{cid}/costs/entriesRaw cost entries (admin)
GET/v1/companies/{cid}/costs/forecastSpend forecast to end of period
GET/v1/companies/{cid}/costs/exportExport cost data
POST/v1/companies/{cid}/costs/topupMove reserve into a team envelope
POST/v1/companies/{cid}/costs/adjustAdmin cost adjustment

​
The roll-up object

{
  "scope": "company",
  "scopeId": "cmp_a1b2c3",
  "period": {
    "start": "2026-04-01T00:00:00Z",
    "end": "2026-04-30T23:59:59Z",
    "label": "monthly"
  },
  "total": {
    "usd": 142.38,
    "tokens": { "input": 14200000, "output": 3800000 }
  },
  "budget": {
    "usd": 500,
    "remaining": 357.62,
    "percentUsed": 28.5
  },
  "breakdown": {
    "llm": { "usd": 98.12, "tokens": 18000000 },
    "tools": { "usd": 32.24 },
    "runtimeServices": { "usd": 12.02 }
  },
  "byTeam": [
    { "id": "tm_g7h8i9", "name": "Marketing", "usd": 64.21 },
    { "id": "tm_j0k1l2", "name": "Engineering", "usd": 78.17 }
  ],
  "trend": {
    "perDay": [
      { "date": "2026-04-10", "usd": 6.32 },
      { "date": "2026-04-11", "usd": 4.88 }
    ]
  }
}

​
Time windows

Every roll-up endpoint takes since and until parameters: 
curl -s "http://localhost:3100/v1/companies/cmp_a1b2c3/costs?since=2026-04-01&until=2026-04-11" \
  -H "Authorization: Bearer $CA_API_TOKEN"
Defaults:
  • since — start of the current fiscal period
  • until — now
Formats:
  • Absolute ISO: 2026-04-11T00:00:00Z
  • Relative: 1h, 24h, 7d, 30d
  • Named: today, yesterday, this_week, this_month, this_quarter

​
Raw cost entries

For everything else (custom dashboards, per-tool analysis, anomaly detection), pull raw entries: 
curl -s "http://localhost:3100/v1/companies/cmp_a1b2c3/costs/entries?since=1h&limit=200" \
  -H "Authorization: Bearer $CA_API_TOKEN"
Each entry has: 
{
  "id": "cst_a1b2c3",
  "companyId": "cmp_d4e5f6",
  "scope": "llm",
  "runId": "run_g7h8i9",
  "taskId": "iss_j0k1l2",
  "agentId": "agt_m3n4o5",
  "teamId": "tm_p6q7r8",
  "model": "claude-sonnet-4-6",
  "inputTokens": 4200,
  "outputTokens": 890,
  "usd": 0.014,
  "at": "2026-04-11T10:42:17Z"
}
Raw entries are immutable. You can query them, export them, and aggregate them, but you cannot delete them. The only way to change a cost is to post an adjust entry that offsets it.

​
Forecast

The forecast endpoint projects spend to end of period based on the recent run rate: 
curl -s http://localhost:3100/v1/companies/cmp_a1b2c3/costs/forecast \
  -H "Authorization: Bearer $CA_API_TOKEN"
Response: 
{
  "periodEnd": "2026-04-30T23:59:59Z",
  "projectedUsd": 412.50,
  "budgetUsd": 500,
  "confidence": 0.78,
  "basedOnDays": 7,
  "assumptions": [
    "Current run rate continues unchanged",
    "No new workflows added during the period"
  ],
  "warnings": [
    "Run rate has been increasing week over week"
  ]
}
Forecasts are rough estimates. Treat them as a direction, not a promise.

​
Top-ups

Move reserve budget into a team envelope that is about to breach: 
curl -s http://localhost:3100/v1/companies/cmp_a1b2c3/costs/topup \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{
    "teamId": "tm_g7h8i9",
    "usd": 50,
    "reason": "critical campaign launch"
  }'
Top-ups are logged in the audit trail and shown on the cost panel with the reason attached.

​
Adjustments

For admin-only corrections (vendor refund, pricing error, billing dispute), post an adjustment: 
curl -s http://localhost:3100/v1/companies/cmp_a1b2c3/costs/adjust \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{
    "offsetUsd": -12.40,
    "scope": "llm",
    "model": "claude-sonnet-4-6",
    "note": "Refund from Anthropic for rate-limit incident 2026-04-08"
  }'
Adjustments are themselves cost entries, with a negative usd field. They show up in audit and cannot be silently removed.

​
Export

For spreadsheets, external dashboards, or long-term archives: 
curl -s "http://localhost:3100/v1/companies/cmp_a1b2c3/costs/export?format=csv&since=2026-04-01" \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -o costs-april.csv
Formats: csv, jsonl, parquet. The parquet export is the most efficient for long periods.

​
Webhooks

EventWhen
cost.breach.softSoft breach on any envelope
cost.breach.hardHard breach on any envelope
cost.breach.catastrophicProcess killed for spend rate
cost.topupTop-up executed
cost.adjustAdmin adjustment posted

​
Next