> ## Documentation Index
> Fetch the complete documentation index at: https://docs.giwa.tokscale.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How Usage Reports Work

> The snapshot, the two comparison windows, and the ranking rules every client and model report is built on.

Tokscale publishes aggregate usage reports at `/metrics`: which AI models developers actually run, which coding clients they run them in, and how both move over time. Most model rankings measure benchmarks or vendor announcements. These measure what developers ran on their own machines.

This page covers the mechanics both report types share. For the reports themselves, see [Client Reports](/usage-tracker/report-clients) and [Model Reports](/usage-tracker/report-models).

## Where the numbers come from

Every report derives from one sealed, published snapshot of Tokscale submissions: the same self-reported usage the open-source CLI collects, aggregated and stripped of identity before publication. Nothing here is gateway-observed.

That places these reports on the bottom rung of the [evidence ladder](/builder-passport/evidence-ladder). They are real data at real volume, and a determined forger could still influence them, which is exactly why the gateway exists. For how the two halves relate, see [The Open-Source Base](/usage-tracker/open-source-base).

The reports are read-only and need no account. They expose aggregate model and client codes with their numbers, and never a username, wallet, or email.

## The published snapshot

`/metrics` is the summary view: when the current snapshot was published, the range of days it covers, how many developers it indexes, and its historical token and estimated-spend totals.

It reports its own absence honestly. If no snapshot is published it says so, and if the snapshot cannot be read it says that instead. Unavailable data is never rendered as zero.

## Two windows, never padded

Every figure is anchored to fixed windows, and the rules are deliberately strict about thin data:

| Rule                      | Behavior                                                |
| ------------------------- | ------------------------------------------------------- |
| Ranking window            | Trailing 30 days, ending at the snapshot's coverage end |
| Comparison window         | The 30 days immediately before it, never overlapping    |
| Directory series          | 30 days, the span the sparkline plots                   |
| Report series             | Up to 365 days                                          |
| No activity in the window | The entry is omitted, never shown as zero               |
| No prior window           | Momentum is withheld, never substituted with zero       |
| Outside the top 100       | Resolves as not ranked, rather than a blank report      |

Each payload declares the number of days it was built from, so a shorter history can never be padded into days that report no usage but look measured. Every daily point carries a real count of distinct developers, so a point exists only because activity exists.

## Publication status

An entry appears before it has enough history to compare, and the pages say so rather than drawing an empty chart. Three states are possible:

* **Awaiting telemetry.** No current 30-day window has been observed yet.
* **Collecting.** A current window exists but a stable prior window does not, so momentum is not yet published.
* **Stable observed sample.** Both windows are present and the full report renders.

<Info>
  Spend figures are estimates priced from tracked token counts, not invoices. The pages label them that way, and a provider bill may differ.
</Info>

## What these reports are not

* Not live. They reflect the most recently published snapshot, not activity in the last hour.
* Not an account balance or billing record. The figures are historical aggregates.
* Not gateway-verified. Routing a client through the gateway is what raises usage above self-reported, and that path is covered in [Client Integration](/gateway/client-integration).
* Not a complete census. Ranking is capped at 100 models and 100 clients per window.

## Next steps

* For per-agent adoption and the models developers pick inside each, see [Client Reports](/usage-tracker/report-clients).
* For per-model token economics and where each model runs, see [Model Reports](/usage-tracker/report-models).
* To contribute your own usage to these aggregates, see [Quickstart: Track Your Usage](/usage-tracker/quickstart).
* For why self-reported data sits where it does, see [Verified Usage and the Evidence Ladder](/builder-passport/evidence-ladder).