Get AI usage

GET/api/v1/ai/usage

scope ai:usageCosts 2 rate-limit units

What the AI has cost over the last 7, 30 or 90 days, broken down by feature, by model and by which credential paid. Figures are what the account is billed, so they match the invoice rather than the provider’s raw price.

Query parameters

Name	Type	Description
`days`optional	`string (enum)`	Window length. Defaults to 30`73090`

Request

curl "https://your-crm.example.com/api/v1/ai/usage?days=30" \
  -H "Authorization: Bearer $RAABTA_API_KEY"

Response · 200 OK

{
  "data": {
    "days": 30,
    "total_cost_usd": 42.18,
    "total_calls": 1834,
    "total_requests": 2210,
    "total_input_tokens": 5920400,
    "total_output_tokens": 411200,
    "total_cached_input_tokens": 3100000,
    "daily": [
      {
        "date": "2026-09-01",
        "cost_usd": 1.62,
        "calls": 71,
        "requests": 84,
        "input_tokens": 228000,
        "output_tokens": 15800,
        "cached_input_tokens": 119000
      }
    ],
    "by_feature": [
      {
        "key": "assistant",
        "cost_usd": 38.9,
        "calls": 1702,
        "requests": 2044,
        "input_tokens": 5512000,
        "output_tokens": 380100,
        "cached_input_tokens": 2980000
      }
    ],
    "by_model": [
      {
        "key": "claude-sonnet-5",
        "cost_usd": 38.9,
        "calls": 1702,
        "requests": 2044,
        "input_tokens": 5512000,
        "output_tokens": 380100,
        "cached_input_tokens": 2980000
      }
    ],
    "by_source": [
      {
        "key": "platform",
        "cost_usd": 42.18,
        "calls": 1834,
        "requests": 2210,
        "input_tokens": 5920400,
        "output_tokens": 411200,
        "cached_input_tokens": 3100000
      }
    ]
  }
}

Response

Wrapped in { data: … }

Name	Type	Description
`days`required	`integer`	Window length in days: 7, 30 or 90
`total_cost_usd`required	`number`	Billed spend over the window
`total_calls`required	`integer`	Calls over the window
`total_requests`required	`integer`	Provider requests over the window
`total_input_tokens`required	`integer`	Tokens sent over the window
`total_output_tokens`required	`integer`	Tokens returned over the window
`total_cached_input_tokens`required	`integer`	Cached input tokens over the window
`daily`required	`object[]`	Zero-filled, oldest day first
`daily[].date`required	`string`	The day, as YYYY-MM-DD in UTC
`daily[].cost_usd`required	`number`	Billed spend that day
`daily[].calls`required	`integer`	Calls that day
`daily[].requests`required	`integer`	Provider requests that day
`daily[].input_tokens`required	`integer`	Tokens sent that day
`daily[].output_tokens`required	`integer`	Tokens returned that day
`daily[].cached_input_tokens`required	`integer`	Cached input tokens that day
`by_feature`required	`object[]`	Costliest first
`by_feature[].key`required	`string`	The feature, model or source this row aggregates
`by_feature[].cost_usd`required	`number`	Billed spend
`by_feature[].calls`required	`integer`	Assistant ticks and one-shot calls
`by_feature[].requests`required	`integer`	Provider HTTP requests
`by_feature[].input_tokens`required	`integer`	Tokens sent
`by_feature[].output_tokens`required	`integer`	Tokens returned
`by_feature[].cached_input_tokens`required	`integer`	Input tokens served from the provider cache
`by_model`required	`object[]`	Costliest first
`by_model[].key`required	`string`	The feature, model or source this row aggregates
`by_model[].cost_usd`required	`number`	Billed spend
`by_model[].calls`required	`integer`	Assistant ticks and one-shot calls
`by_model[].requests`required	`integer`	Provider HTTP requests
`by_model[].input_tokens`required	`integer`	Tokens sent
`by_model[].output_tokens`required	`integer`	Tokens returned
`by_model[].cached_input_tokens`required	`integer`	Input tokens served from the provider cache
`by_source`required	`object[]`	business is your own provider key; platform is capacity we served
`by_source[].key`required	`string`	The feature, model or source this row aggregates
`by_source[].cost_usd`required	`number`	Billed spend
`by_source[].calls`required	`integer`	Assistant ticks and one-shot calls
`by_source[].requests`required	`integer`	Provider HTTP requests
`by_source[].input_tokens`required	`integer`	Tokens sent
`by_source[].output_tokens`required	`integer`	Tokens returned
`by_source[].cached_input_tokens`required	`integer`	Input tokens served from the provider cache

Errors

Status	Code	When
400	`bad_request`	The request could not be parsed: malformed JSON, an invalid cursor, or a query parameter of the wrong shape.
400	`validation_error`	The body or query failed validation. `details` lists each failing field with a `path` and a `message`.
401	`unauthorized`	No usable API key: the Authorization header is missing or malformed, or the key is unknown, revoked or expired. The three are deliberately indistinguishable.
403	`forbidden`	The key is valid but lacks the scope this endpoint requires, or the request came from an address outside the key’s IP allowlist. The message says which.
403	`account_suspended`	The account this key belongs to is suspended. Rotating the key will not help; contact support.
429	`rate_limited`	The per-key budget, or the per-IP budget for failed authentication, is exhausted. Honour `Retry-After` before retrying.
500	`internal`	Something failed on our side. Safe to retry with the same Idempotency-Key; quote `request_id` if it persists.