# Token usage

> Advisory model-token meter for BYOK spend estimates — dashboard, CLI, and customer MCP. Not compute credits and not fleet usage.

Part of the jurniti developer docs — canonical page: https://www.jurniti.com/docs/token-usage · full docs index: https://www.jurniti.com/docs/llms.txt

## Model tokens vs compute usage

jurniti measures two different things that both say “usage” in casual speech:

| Surface | What it answers | Where |
| --- | --- | --- |
| **Token usage** | How many **model tokens** your agents used, and an **estimated BYOK cost** | Dashboard **Token usage**, `jurniti token-usage`, MCP `token_usage` |
| **Fleet usage** | How many **VMs** you have and **monthly plan spend** (plus credits burn when relevant) | `jurniti usage`, MCP `usage` |
| **Usage tiers / credits** | Prepaid **compute** hours (On-Demand / Spot) | [Usage tiers & credits](/docs/usage-tiers), `jurniti credits` |

**Token usage is advisory only.** jurniti does not resell model tokens or charge you for them. You bring your own keys (BYOK); the meter helps you see spend transparency. Estimates use public list prices and can be partial when a model is unknown.

> **Not a free tier:** Token usage does not unlock free compute. Agents still require a paid plan or prepaid credits — same [no free trial / no free tier](/docs/quickstart) rule.

## Dashboard

1. Open **[Token usage](https://app.jurniti.com/dashboard/token-usage)** (Fleet
   sidebar — labeled **Usage** / Token usage).
2. Toggle **Session** or **Week**.
3. Read totals, then breakdowns by provider, model, harness, and VM.
4. On an agent detail page, the same meter appears scoped to that VM.

Session means “since the current run(s) started” (tied to when VMs entered
running). Week is the UTC calendar week.

## CLI

Requires the [CLI](/docs/installation) and `jurniti login` (or `JURNITI_API_KEY`).

```bash
# Fleet-wide (default window: session)
jurniti token-usage

# This UTC week
jurniti token-usage --window week

# One owned VM
jurniti token-usage --vm <vm-id> --window week

# Raw JSON for scripts / CI
jurniti token-usage --window week --json
```

Human output ends with a reminder that estimates are **not a jurniti charge**
and are distinct from `jurniti usage` (fleet / MRR).

Full verb list: [CLI reference](/docs/cli-reference).

## MCP (your agent)

Mount the **customer** server (not operator MCP):

```bash
claude mcp add jurniti -- jurniti mcp
```

| Tool | CLI equivalent | Notes |
| --- | --- | --- |
| `token_usage` | `jurniti token-usage` | Optional `window`: `session` (default) or `week` |
| `vm_token_usage` | `jurniti token-usage --vm` | Required `id` (VM); same windows |

Same account and key as the CLI. Use after `vm_run` when you want cost
transparency without opening the browser.

See also [MCP](/docs/mcp).

## When data is empty

- No events yet for the window → totals stay zero / `data_available` false.
- Not every harness reports token telemetry the same way; empty is normal until
  the guest meter has samples.
- `has_partial_cost` means some rows lack a price table entry — token counts
  still show; $ may be incomplete.

## Related

- [Dashboard](/docs/dashboard) — where the UI meter lives
- [Usage tiers & credits](/docs/usage-tiers) — compute billing, not model tokens
- [CLI reference](/docs/cli-reference) — full verb tree
- [MCP](/docs/mcp) — agent tools including `token_usage`