> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toktra.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Usage monitoring
> Understand and analyze your organization's LLM token consumption across providers, teams, and time.
The Toktra usage dashboard gives you a complete picture of how your organization uses AI — across every provider, model, department, and user. This guide explains how to read the data, apply filters, export records, and act on efficiency insights.
## The Overview page
The **Overview** page is your starting point after logging in. It shows four summary tiles for the last 30 days:
| Tile | What it shows |
| ------------------ | ----------------------------------------------------------- |
| Enrolled Devices | Number of devices with active agent certificates |
| Active Users | Number of users with at least one usage event |
| Total Tokens (30d) | Sum of estimated input + output tokens across all providers |
| Protected | Whether active monitoring is running |
The **Recent Activity** panel below summarizes the number of provider usage records in the selected window.
## The Usage page
Navigate to **Usage** in the sidebar to open the detailed usage view.
### Time range
Use the **7d / 30d / 90d** buttons in the top-right corner to change the analysis window. Charts and tables update immediately.
### Tokens by provider
The **Tokens by Provider** bar chart breaks input and output token counts by provider: OpenAI, Anthropic, Azure OpenAI, and GCP Vertex AI. Use this view to understand which services your organization relies on most.
### Top users by token volume
The **Top Users** table ranks users by total tokens consumed in the selected period. A progress bar shows each user's share relative to the highest consumer in the period.
### Filtering usage
Use the user filter on the Usage page, or pass `user_id` as a query parameter to `GET /v1/usage` to scope the view to a single employee.
Filter by model name — for example, `gpt-4o`, `claude-3-5-sonnet`, or `gemini-1.5-pro` — to understand which model tiers are in use across your org.
Department-level filtering is available when department budgets are configured. Navigate to **Budget → Department Hierarchy** for per-department usage, or add a `department_id` filter on the usage API endpoint.
Set a custom date range using `start_date` and `end_date` query parameters (format: `YYYY-MM-DD`) on the API, or use the time range selector in the dashboard.
## Understanding token counts
Toktra reports two types of token counts:
| Type | Description |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Estimated** | Counts produced by the on-device token estimator. Available in real time as usage happens. |
| **Reconciled** | Authoritative counts pulled from provider admin APIs (OpenAI, Anthropic, Azure, GCP). Matched against device telemetry and used for billing, budget enforcement, and efficiency scoring. |
Reconciled counts are the source of truth for billing and budgets. Estimated counts power real-time dashboards because they are available immediately, before the provider polling cycle completes.
### Provider polling
Toktra polls provider admin APIs to fetch authoritative token counts for your organization:
| Provider | Source |
| ------------- | ------------------------------------- |
| OpenAI | OpenAI Admin API (organization usage) |
| Anthropic | Anthropic API (Claude usage metrics) |
| Azure OpenAI | Azure ARM API (resource usage) |
| GCP Vertex AI | Cloud Billing / Metrics API |
Once a polling cycle completes, reconciled counts are reflected in the dashboard on the next page load.
## Exporting usage data
Export raw usage records for analysis in BI tools, compliance audits, or finance systems.
Call `POST /v1/exports` with the date range, format, and scope:
```json theme={null}
{
"date_from": "2026-03-01",
"date_to": "2026-03-31",
"format": "csv",
"scope": "users",
"filters": {
"providers": ["openai", "anthropic"]
}
}
```
Valid `format` values: `csv`, `json`.
Valid `scope` values: `users`, `teams`, `models`, `providers`.
The export runs asynchronously. Poll `GET /v1/exports/{job_id}` until `status` is `ready`.
Call `GET /v1/exports/{job_id}/download`. The response redirects you to a pre-signed download URL. The link expires after one hour.
Use the `filters.model_names` field to export only usage from expensive models — for example, `gpt-4o` or `claude-3-opus` — when preparing cost review reports.
## Scheduled reports
Toktra generates and emails usage, budget, and efficiency reports on a schedule you configure. Reports include:
* Usage summary by provider and model
* Top users by token volume
* Budget utilization vs. limits
* Efficiency scores and coaching highlights
Configure report frequency and recipients at **Settings → Scheduled Reports**.
## Efficiency scores and team leaderboards
Toktra computes per-user and per-team **efficiency scores** from usage patterns. Scores reflect how effectively tokens are being used — users who achieve more productive output with fewer tokens score higher.
### Performance dashboard
Navigate to **Performance** to see:
* **Individual scores:** Each user's current efficiency score with a trend indicator.
* **Team leaderboard:** Rankings by efficiency within a department. An anonymization toggle lets you share the leaderboard without exposing individual names.
* **Model access tiers:** Users are assigned `standard`, `advanced`, or `premium` tiers based on their efficiency score, controlling which models they can access.
### AI adoption scorecards
Toktra computes AI adoption scorecards nightly per employee, team, and department. Navigate to **Scorecards** to view:
* Adoption rate (percentage of eligible employees actively using AI tools)
* Token consumption trends over time
* Model diversity (number of distinct models used)
* Efficiency trend over 30 and 90 days
## 30/90-day forecasting
The **Usage Forecast** page projects token consumption 30 and 90 days forward based on the last 90 days of reconciled data.
Each forecast includes a **trend classification**:
| Classification | Meaning |
| -------------- | ----------------------------------------------- |
| Accelerating | Usage growing faster than the baseline trend |
| Steady | Usage growing in line with the historical trend |
| Decelerating | Usage growth slowing |
| Declining | Usage falling month-over-month |
Use the forecast view when planning budget periods or capacity for the next quarter.
## ROI calculator
Navigate to **Performance → ROI Calculator** to model the cost impact of different model configurations. Input your current token volumes, model mix, and cost per token to see projected savings from shifting workloads to more efficient models or lower-cost providers.