---
title: "GET /api/v1/admin/ai/usage"
method: GET
path: "/api/v1/admin/ai/usage"
tags: ["Administration", "AI Operations"]
---

# GET /api/v1/admin/ai/usage

`GET /api/v1/admin/ai/usage`

Returns every application-recorded model purpose, status, token count, and estimated gateway cost from the model-call ledger. Model-call rows use bounded offset pagination without changing full-period aggregates. Cost values remain estimates, not provider invoices.

## Query parameters

- `from` string, date-time
- `to` string, date-time
- `limit` integer
- `model` string
- `productId` integer
- `modelCallsOffset` integer, nullable

## Cookies

- `billing_session` string

## Response `200`

Model usage and call metadata.

- object
  - `byModel` object[], required
    - `blockedCalls` integer, required
    - `cacheReadTokens` integer, required
    - `cacheWriteTokens` integer, required
    - `calls` integer, required
    - `errorCalls` integer, required
    - `estimatedCostMicrousd` integer, required
    - `gatewayCostMicrousd` integer, nullable, required
    - `inputTokens` integer, required
    - `model` string, required
    - `outputTokens` integer, required
    - `successCalls` integer, required
    - `totalTokens` integer, required
  - `byPurpose` object[], required
    - `blockedCalls` integer, required
    - `cacheReadTokens` integer, required
    - `cacheWriteTokens` integer, required
    - `calls` integer, required
    - `errorCalls` integer, required
    - `estimatedCostMicrousd` integer, required
    - `gatewayCostMicrousd` integer, nullable, required
    - `inputTokens` integer, required
    - `outputTokens` integer, required
    - `successCalls` integer, required
    - `totalTokens` integer, required
    - `purpose` 'agent' | 'compaction' | 'compaction_prefix' | 'safety' | 'web_search' | 'title' | 'evaluation', required
  - `coverage` 'all_model_calls' | 'primary_agent_turns_only', required
  - `generatedAt` string, date-time, required
  - `modelCalls` object[], required
    - `cacheReadTokens` integer, required
    - `cacheWriteTokens` integer, required
    - `chargeScope` 'customer' | 'platform', required
    - `conversationId` string, uuid, required
    - `durationMs` integer, required
    - `errorClass` string, nullable, required
    - `estimatedCostMicrousd` integer, required
    - `eventId` string, required
    - `gatewayCostMicrousd` integer, nullable, required
    - `gatewayLogId` string, nullable, required
    - `inputTokens` integer, required
    - `model` string, required
    - `occurredAt` string, date-time, required
    - `outputTokens` integer, required
    - `provider` string, required
    - `purpose` 'agent' | 'compaction' | 'compaction_prefix' | 'safety' | 'web_search' | 'title' | 'evaluation', required
    - `status` 'success' | 'error' | 'blocked', required
    - `submissionId` string, nullable, required
    - `totalTokens` integer, required
    - `traceId` string, required
    - `turnId` string, required
  - `pagination` object, required
    - `modelCalls` object, required
      - `hasMore` boolean, required
      - `limit` integer, required
      - `offset` integer, required
  - `period` object, required
    - `from` string, date-time, required
    - `to` string, date-time, required
  - `provenance` 'mixed_gateway_estimate', required
  - `summary` object, required
    - `blockedCalls` integer, required
    - `cacheReadTokens` integer, required
    - `cacheWriteTokens` integer, required
    - `calls` integer, required
    - `errorCalls` integer, required
    - `estimatedCostMicrousd` integer, required
    - `estimatedCostProvenance` 'estimated_app', required
    - `gatewayCostMicrousd` integer, nullable, required
    - `gatewayCostAsOf` string, date-time, nullable, required
    - `gatewayCostProvenance` 'gateway_reported', required
    - `gatewayCoveragePercent` number, required
    - `gatewayPendingCalls` integer, required
    - `gatewayReconciledCalls` integer, required
    - `gatewayReconciliationStatus` 'none' | 'partial' | 'complete', required
    - `inputTokens` integer, required
    - `outputTokens` integer, required
    - `successCalls` integer, required
    - `totalTokens` integer, required

## Other responses

- `400` — The query, pagination, or session cookie is invalid.
- `401` — No valid global administrator session exists.
- `503` — AI operations telemetry is unavailable.

---

[API](https://skmtc.dev/expertschat/apis/billing-core-api.md) · [All operations](https://skmtc.dev/expertschat/apis/billing-core-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/expertschat/billing-core-api/revisions/c6d0e986ce32/schema)