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

# Usage statistics

> Inspect local usage by time, Agent, project, provider, and model.

**Usage Statistics** shows the Agent usage Vibex has recorded. It is an observability tool, **not a billing page** — actual prices, quotas, and invoices are still decided by the provider. Vibex records no cost and has no price field.

Entry points: the **Usage Statistics** button in the sidebar, or the token ring in Composer (**Open usage statistics**).

## Choose a time range

The toolbar offers four ranges and picks the bucket size from the range you choose:

| Range       | Meaning                        | Bucket |
| ----------- | ------------------------------ | ------ |
| **Today**   | Today in the system time zone. | Hour   |
| **7 days**  | The last seven days.           | Day    |
| **30 days** | The last thirty days.          | Day    |
| **All**     | Every record retained locally. | Month  |

When no records are available the page shows an empty state; it never treats an unknown value as zero.

## Filters and grouping

You can combine five filters: **Agent**, **Model provider**, **Model**, **Project**, **Session**.

Results can be grouped along five dimensions, which are the tabs above the table: **Time**, **Agent**, **Project**, **Model provider**, **Model**.

<Note>
  The **Project** dimension maps to projects in the sidebar, and one project may contain several workspaces. **Session is a filter only** and cannot be used as a grouping dimension.
</Note>

## Read the metrics

The summary area shows six metrics:

| Metric                 | Meaning                                                                                                    |
| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Total tokens**       | The combined total of every token category.                                                                |
| **API requests**       | The number of observed API requests; when an adapter provides no per-request data, this becomes **Turns**. |
| **Input** / **Output** | Input and output tokens.                                                                                   |
| **Cached read**        | Cached read tokens.                                                                                        |
| **Cache hit rate**     | Cached reads as a share of the computable denominator.                                                     |

The grouped table has these columns: the dimension name, **Requests**, **Total**, **Input**, **Output**, **Cache**, **Hit rate**, **Last activity**, **Coverage**.

### What Coverage means

**Coverage** tells you how much to trust the numbers in that row:

| Display                         | Meaning                                                                    |
| ------------------------------- | -------------------------------------------------------------------------- |
| **Reported**                    | The adapter reported everything.                                           |
| **Derived from input + output** | The total is derived from input plus output rather than reported directly. |
| **Partial**                     | Only part of the data was reported.                                        |
| **Not reported**                | There is no data.                                                          |

Hovering reveals a finer breakdown (complete / partial / baseline only / unreported / unsupported).

<Warning>
  **Never read `Not reported` or `Partial` as zero**, and do not use either to estimate a provider invoice. When a provider field is missing, Vibex keeps it unknown instead of filling in a guess.
</Warning>

## Trend views

| View        | Description                                                                                                                                                              |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Trend**   | A stacked bar chart you can switch between **Total** / **Input** / **Output** / **Cache**; click the legend to filter.                                                   |
| **Heatmap** | A 365-day calendar heatmap showing daily activity density; shown as unavailable when there is no annual data.                                                            |
| **Models**  | A per-day share of each model (100% stacked) for the top 10 models, with the rest grouped into **Other** and **Unknown**. Switch between **Turns** and **Total tokens**. |

While refreshing, the page keeps the previous result and marks it stale. If loading fails, it prefers the previous authoritative result and shows **Refresh failed; showing previous data**.

## Data boundaries

* Usage comes from Agent executions recorded by the authoritative runtime and from adapter reports. **The authoritative runtime is the authoritative source of these statistics.**
* Usage Statistics does **not** read full prompts, file contents, terminal output, or provider keys.
* **Mobile does not show usage detail** — the mobile usage page only shows session counts and says "Usage details are available on the desktop host."
* A single query has a row limit (100000 rows); exceeding it returns `agent_usage_query_too_large`.

When you export diagnostics, follow the redaction requirements in [Privacy and recovery](/docs/en/privacy-and-recovery).