# Metrics Contract

All analytics endpoints filter to `logs.type = 2`.

## Core Metrics

- **Calls:** count of matching log rows.
- **Input tokens:** sum of `prompt_tokens`.
- **Output tokens:** sum of `completion_tokens`.
- **Cache creation tokens:** `other.cache_creation_tokens`, parsed as bigint when present, otherwise `0`.
- **Cache read tokens:** `other.cache_tokens`, parsed as bigint when present, otherwise `0`.
- **Total tokens:** input + output + cache creation + cache read.
- **Quota:** sum of `quota`.
- **Cost:** quota converted to USD by `quota / 500000`.

The quota conversion constant is defined in `lib/metrics.ts` as `QUOTA_UNITS_PER_USD`.

## Dimensions

- **User:** grouped by `logs.user_id` and `logs.username`, displayed with `users.display_name` when present.
- **Model:** grouped by real model name. Real model is `other.upstream_model_name` when present, otherwise `logs.model_name`.
- **Channel:** grouped by `logs.channel_id`, displayed with `channels.name` when present.
- **Token name:** grouped by trimmed `logs.token_name`; blank values display as the localized unnamed-token label.

## Time Handling

Date ranges are Unix timestamps in seconds. Day, week, month, and hour buckets are computed in the `Asia/Shanghai` timezone.

Invalid timestamps or reversed ranges return HTTP 400.