> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmuster.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Costs

> Track and query AI cost data via the REST API.

## Ingest cost event

```bash theme={null}
POST /api/v1/costs/events
```

No authentication required. Cost events are created automatically when you include `token_input`, `token_output`, and `model` in your quality signal POST.

**Body:**

```json theme={null}
{
  "agent_id": "invoice-processor-v2",
  "job_id": "job-001",
  "model": "gpt-4o",
  "provider": "openai",
  "input_tokens": 1247,
  "output_tokens": 312
}
```

**Response:**

```json theme={null}
{
  "event_id": "uuid",
  "cost_usd": 0.0343,
  "cost_display": 0.03,
  "display_currency": "USD"
}
```

## Cost summary

```bash theme={null}
GET /api/v1/costs/summary?days=30
```

```json theme={null}
{
  "period_days": 30,
  "total_cost_usd": 5481.89,
  "total_cost_display": 5481.89,
  "unattributed_cost_usd": 0,
  "display_currency": "USD",
  "daily_trend": [
    {
      "date": "2026-02-22",
      "cost_usd": 190.54,
      "cost_display": 190.54
    }
  ]
}
```

## Agent cost detail

```bash theme={null}
GET /api/v1/costs/agents/{agent_id}?days=30
```

## Department costs

```bash theme={null}
GET /api/v1/costs/departments
```

Returns this month's spend grouped by department, with budget utilisation if budgets are set.

## Set department budget

```bash theme={null}
POST /api/v1/costs/budgets
```

```json theme={null}
{
  "department": "Finance",
  "month": "2026-03-01",
  "budget_amount": 5000.00
}
```