---
title: "AI spend"
method: GET
path: "/v1/spend/ai"
tags: ["Spend"]
---

# AI spend

`GET /v1/spend/ai`

## Request

- Base URL: `https://api.1claw.co`
- URL: `https://api.1claw.co/v1/spend/ai`
- Auth: HTTP bearer

Inference spend for the org over a window (default the last 30 days):
totals with the previous equal-length window for comparison, a time series
by provider, and breakdowns by provider, by model and by agent — each agent
with its `shroud_config` daily budget, today's spend against it and the
requests Shroud blocked for budget. `limits` carries router-key spend caps,
the credit balance and 1Claw's inspection fees for the window (a separate
number from provider cost). Every request is priced at ingest from the
price card (`GET /v1/spend/ai/prices`); a request whose provider has no
card is counted as unpriced, not free. Human and platform callers only.
Backs the dashboard's Spend tab; the same numbers reach an org's own
collector as OTEL metrics `ai.cost_usd`, `ai.tokens.input`, `ai.tokens.output`.

## Query parameters

- `from` string, date-time
- `to` string, date-time
- `interval` 'day' | 'week' | 'month'
- `agent_id` string, uuid
- `provider` string

## Response `200`

Spend

- AiSpend
  - `generated_at` string, date-time, required
  - `window` object, required
    - `from` string, date-time
    - `to` string, date-time
    - `interval` string
    - `previous_from` string, date-time
    - `previous_to` string, date-time
    - `days` number
  - `totals` AiSpendTotals, required
    - `cost_usd` number
    - `tokens_input` integer
    - `tokens_output` integer
    - `tokens` integer
    - `requests` integer
    - `blocked` integer
    - `unpriced_requests` integer
    - `agents` integer
    - `models` integer
    - `avg_cost_per_day` number
    - `cost_per_request` number
    - `cost_per_mtok` number
  - `previous` AiSpendTotals, required
    - `cost_usd` number
    - `tokens_input` integer
    - `tokens_output` integer
    - `tokens` integer
    - `requests` integer
    - `blocked` integer
    - `unpriced_requests` integer
    - `agents` integer
    - `models` integer
    - `avg_cost_per_day` number
    - `cost_per_request` number
    - `cost_per_mtok` number
  - `series` object[], required
    - `bucket` string, date-time
    - `provider` string
    - `cost_usd` number
    - `tokens` integer
    - `requests` integer
  - `by_provider` object[], required
    - `provider` string
    - `cost_usd` number
    - `tokens` integer
    - `requests` integer
    - `previous_cost_usd` number
    - `share_pct` number
    - `trend_pct` number, nullable
  - `by_model` object[], required
    - `provider` string
    - `model` string
    - `cost_usd` number
    - `tokens_input` integer
    - `tokens_output` integer
    - `requests` integer
    - `previous_cost_usd` number
    - `priced` boolean
    - `share_pct` number
    - `trend_pct` number, nullable
  - `by_agent` object[], required
    - `agent_id` string, uuid
    - `agent_name` string
    - `is_active` boolean
    - `cost_usd` number
    - `tokens` integer
    - `requests` integer
    - `blocked` integer
    - `top_model` string, nullable
    - `top_provider` string, nullable
    - `previous_cost_usd` number
    - `last_request_at` string, date-time, nullable
    - `daily_budget_usd` number, nullable
    - `today_cost_usd` number
    - `blocked_by_budget` integer
    - `max_tokens_per_request` integer, nullable
    - `max_requests_per_day` integer, nullable
    - `share_pct` number
    - `trend_pct` number, nullable
    - `budget_used_pct` number, nullable
  - `limits` object, required
    - `agents_with_daily_budget` integer
    - `agents_over_80pct` integer
    - `agents_at_cap` integer
    - `blocked_by_budget` integer
    - `router_keys` object[]
      - `key_id` string, uuid
      - `agent_id` string, uuid
      - `agent_name` string
      - `name` string
      - `spent_usd` number
      - `cap_usd` number, nullable
      - `last_used_at` string, date-time, nullable
    - `credit_balance_usd` number
    - `inspection_fees_usd` number
    - `billing_tier` string

## Other responses

- `400`: Invalid request
- `401`: Authentication required or invalid
- `403`: Insufficient permissions

---

[API](https://skmtc.dev/1claw/apis/1claw-api.md) · [All operations](https://skmtc.dev/1claw/apis/1claw-api/llms.txt) · [OpenAPI document](https://skmtc.dev/1claw/apis/1claw-api/revisions/ae109b496830?raw)