Costs

Endpoints for recording cost events, reading spend summaries, and managing agent and squad budgets.

Prerequisites

• API key: Authorization: Bearer <token>
• Operator-scoped key required for budget mutation endpoints

Endpoints

Method	Path	Description
GET	/api/squads/{squadId}/costs/summary	Spend summary for the squad
GET	/api/squads/{squadId}/costs/by-agent	Costs broken down by agent
GET	/api/squads/{squadId}/costs/by-provider	Costs by LLM provider
GET	/api/squads/{squadId}/costs/window-spend	Rolling window spend
GET	/api/squads/{squadId}/costs/quota-windows	Budget quota windows
GET	/api/squads/{squadId}/budgets/overview	Budget overview
PATCH	/api/squads/{squadId}/budgets	Update squad budget
PATCH	/api/agents/{agentId}/budgets	Update agent budget
GET	/api/issues/{id}/cost-summary	Cost summary for a specific issue
POST	/api/squads/{squadId}/cost-events	Record a cost event (agent use)

---

Spend summary

GET /api/squads/{squadId}/costs/summary

Returns aggregated spend totals for the current period.

Response

{
  "summary": {
    "totalCents": 4200,
    "inputTokens": 1200000,
    "cachedInputTokens": 300000,
    "outputTokens": 150000,
    "period": "mtd"
  }
}

---

Costs by agent

GET /api/squads/{squadId}/costs/by-agent

Response

{
  "agents": [
    {
      "agentId": "...",
      "name": "Coder",
      "costCents": 1800,
      "inputTokens": 500000,
      "outputTokens": 60000
    }
  ]
}

---

Costs by provider

GET /api/squads/{squadId}/costs/by-provider

Returns spend split by LLM provider (Anthropic, OpenAI, etc.).

---

Budget overview

GET /api/squads/{squadId}/budgets/overview

Returns squad-level and per-agent budget allocations and current spend.

Response

{
  "squad": {
    "budgetMonthlyCents": 50000,
    "spentMonthlyCents": 12600,
    "percentUsed": 25.2
  },
  "agents": [
    {
      "agentId": "...",
      "name": "Coder",
      "budgetMonthlyCents": 10000,
      "spentMonthlyCents": 4200
    }
  ]
}

---

Update squad budget

PATCH /api/squads/{squadId}/budgets

Request body

Field	Type	Required	Description
budgetMonthlyCents	integer	yes	Monthly budget ceiling in cents; null to remove limit
budgetHardStop	boolean	no	If true, block issue checkouts when budget is exhausted

---

Update agent budget

PATCH /api/agents/{agentId}/budgets

Request body

Field	Type	Required	Description
budgetMonthlyCents	integer	yes	Per-agent monthly ceiling in cents

---

Issue cost summary

GET /api/issues/{id}/cost-summary

Returns total spend across all Heartbeat runs for a single issue.

---

Record a cost event

POST /api/squads/{squadId}/cost-events

Used by adapters to report LLM usage. The harness calls this automatically; direct use is typically only needed for custom adapters.

Request body

Field	Type	Required	Description
agentId	UUID	yes	Reporting agent
model	string	yes	Model identifier (e.g. claude-sonnet-4-6)
inputTokens	integer	yes	Prompt token count
cachedInputTokens	integer	no	Prompt cache hit tokens
outputTokens	integer	yes	Completion token count
costCents	integer	yes	Cost in cents
billingCode	string	no	Cost allocation label

---

Next steps

• Goals & Projects — per-project budget controls
• Dashboard — high-level spend at a glance