Review costs

Overview

Agent Barn’s Costs view is a usage report. It shows spend reported by LiteLLM and attributes it to Agents through their individual LiteLLM keys. It is not an invoice, payment system, budget, quota, or spending limit.

Use the Costs page to answer four operational questions:

What the report includes

The Organization cost summary contains the following information:

Costs are displayed in US dollars.

The report can include active, stopped, errored, and soft-deleted Agents. An Agent without a LiteLLM key is omitted from the Organization summary, because there is no key identity through which spend can be attributed.

Access model

Organization-wide and per-Agent cost access are separate authorizations.

The Organization summary requires the Organization-level cost.read Permission. The fixed Organization Owner and Admin Roles contain it.

All three fixed Agent Access Roles — Viewer, Editor, and Owner — contain cost.read, but only for the Agents made accessible through those roles. An Agent Access Role never grants access to the Organization-wide summary.

Before you begin

If you hold only Agent Viewer, Editor, or Owner access, use the per-Agent API described in Cost API. Those roles do not provide access to the Organization-wide page.

Interpret Agent statuses

Cost-facing statuses are reporting labels.

These values are not the same API contract as the persisted Agent lifecycle enum.

Cost and runtime state also describe different things. Stopping an Agent prevents new runtime work, but it does not remove spend already reported for its key.

How cost attribution works

Agent Barn attributes spend through a per-Agent LiteLLM identity:

1. Agent
2. Per-Agent LiteLLM key
3. LiteLLM spend report
4. Agent Barn Costs

The diagram reads left to right: an Agent holds a per-Agent LiteLLM key; requests made with that key appear in the LiteLLM spend report; Agent Barn Costs joins the key identity back to the Agent.

When an Organization summary is requested, Agent Barn:

1. Loads active and soft-deleted Agents belonging to the Organization.
2. Omits Agents that have no LiteLLM key.
3. Decrypts each stored per-Agent key inside the service boundary.
4. Derives the key identity used by LiteLLM’s report.
5. Matches LiteLLM report entries to Agents.
6. Aggregates total spend, daily spend, model spend, token counts, and Agent spend.
7. Returns the calculated report to the caller.

Cost data is fetched from LiteLLM when the report is requested. The Costs domain does not persist the resulting cost records.

Only usage reported through the relevant Agent key can be joined to that Agent. Model requests made outside the configured Agent Barn and LiteLLM path do not automatically appear in this report.

Reporting boundaries

Interpret the Costs page as an operational attribution report. It does not provide:

• Provider invoices
• Payment history
• Account balances
• Budgets or alerts
• Per-Agent spending limits
• Quota enforcement
• Conversation-level cost allocation
• Tool-call-level cost allocation
• A permanent Agent Barn cost ledger
• Platform-wide cost oversight

Conversation Messages, Tool Calls, Logs, and runtime Telemetry do not feed the cost calculation. They may help explain usage, but LiteLLM remains the reporting source.

The report can differ from a provider invoice because of:

• Different reporting windows
• Provider-side adjustments
• Reporting delays
• Requests made outside Agent Barn’s per-Agent keys
• Display-name normalization
• Different rounding and aggregation rules

Use the provider’s billing records as the financial authority for invoicing and reconciliation.

Cost API

All endpoints require an authenticated Agent Barn access token.

Organization summary

GET /api/v1/organizations/{organization_id}/costs/summary
Authorization: Bearer <access-token>

Apply an explicit date range with both query parameters:

GET /api/v1/organizations/{organization_id}/costs/summary?start_date=2026-08-01&end_date=2026-08-29
Authorization: Bearer <access-token>

Example request:

curl \
  --request GET \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  "$AGENT_BARN_URL/api/v1/organizations/$ORGANIZATION_ID/costs/summary?start_date=2026-08-01&end_date=2026-08-29"

The response contains totalCost, agents, byModel, and timeSeries. Each Agent entry includes its identity, status, configured model, total cost, token totals, and available model breakdown.

This endpoint requires Organization-level cost.read.

Individual Agent cost

GET /api/v1/organizations/{organization_id}/costs/agents/{agent_id}
Authorization: Bearer <access-token>

Example request:

curl \
  --request GET \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  "$AGENT_BARN_URL/api/v1/organizations/$ORGANIZATION_ID/costs/agents/$AGENT_ID"

This endpoint requires effective cost.read authority for the requested Agent. The fixed Agent Viewer, Editor, and Owner Access Roles contain that Permission.

An inaccessible Agent returns 404 Not Found, so the endpoint does not reveal whether an Agent exists in another access scope.

Authorization behavior

Security considerations

Cost data is billing-sensitive Organization information.

Agent Barn decrypts per-Agent LiteLLM keys inside the service to derive their reporting identity. The plaintext key is never part of the cost response.

Troubleshooting

Next steps

1. Correlate spend changes with conversations and Tool Calls.
2. Review who holds Organization-wide and per-Agent cost visibility.
3. Verify unexpected totals against LiteLLM and provider reporting.
4. Reconcile invoices against the provider’s billing records, not this report.
5. Continue to Administer the platform.