UsageGroup

One row in the all-usage report. Every dimension is content-free and can survive history deletion without retaining a chat or message identity.

Type object

Shape

Field	Type	Description
utc_dayrequired	string
surfacerequired	AiSurface
providerrequired	AiProviderId	Extensible provider token such as openai, ollama, or koru.
modelrequired	string
reasoningrequired	ReasoningChoice	A provider's reasoning setting - `ai.db`'s nine-token CHECK.
statusrequired	AttemptStatus
prompt_template_versionrequired	string
totalsrequired	UsageTotals	Content-free aggregate measurements for one usage scope or reporting row. Provider token fields remain optional so an unavailable measurement cannot be mistaken for a reported zero. Context counts and bytes are measured by Koru itself and therefore have exact zero values.

Example

{
  "utc_day": "string",
  "surface": "standalone",
  "provider": "string",
  "model": "string",
  "reasoning": "default",
  "status": "pending",
  "prompt_template_version": "string",
  "totals": {
    "attempts": 0,
    "attempts_with_reported_usage": 0,
    "request_payload_bytes": 0,
    "web_search_calls": 0,
    "context_payload_bytes": 0,
    "message_count": 0,
    "context_document_count": 0,
    "context_message_block_count": 0,
    "prompt_tokens": 0,
    "cached_prompt_tokens": 0,
    "completion_tokens": 0,
    "reasoning_tokens": 0,
    "total_tokens": 0,
    "average_context_assembly_ms": 0,
    "average_provider_start_ms": 0,
    "average_time_to_first_token_ms": 0,
    "average_generation_ms": 0,
    "average_total_ms": 0,
    "good_feedback": 0,
    "bad_feedback": 0
  }
}

The contract has no example values, so example bodies are generated from each schema: every field is shown with a placeholder of its type.

Generated from contract version 1. Last updated November 12, 2026.