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

# Usage

> Track credits, VM runtime, tokens, and runs across your tasks in the Usage settings.

The Usage page reports what your tasks consumed: credits spent on VM runtime, VM uptime, LLM tokens, and agent runs. It reads from a single endpoint and presents the same data two ways — a glanceable **Overview** and a deep **Explore** view. Open it under **Settings → Usage**.

Usage attributes everything to tasks. Credits shown here are VM-runtime credits only; tokens are reported for insight but never billed. For your full charged total, including warm-slot snapshot refreshes, see [Billing](/guides/billing) and [Billing & Credits](/concepts/billing-and-credits).

## Overview vs Explore

The page has two tabs. Overview is the default landing surface; Explore is opened explicitly.

| Tab          | What it shows                                                                                                                                                                             |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Overview** | A glanceable dashboard: KPI cards (credits, VM runtime, tokens), a usage-by-time chart, and breakdowns by model and project. Each card drills into Explore pre-pivoted to that dimension. |
| **Explore**  | The full explorer: pick a metric, group by any dimension, filter, sort and page the task ledger, and export CSV.                                                                          |

Both tabs share the same filtered window, so switching tabs keeps your date range and filters.

## Metrics

The KPI cards and charts surface four metrics. Credits is the money metric, runtime is what drives it, and tokens are work done — never billed.

| Metric                     | Field                                       | Meaning                                                                        |
| -------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------ |
| **Credits**                | `credits_used`                              | VM-runtime cost, derived only from runtime intervals. The primary metric.      |
| **VM runtime**             | `vm_uptime_seconds`                         | Active workspace VM time. Drives credits. Still-running sessions are included. |
| **Tokens**                 | `tokens_in` / `tokens_out` / `total_tokens` | LLM tokens consumed. Shown for insight; not billed.                            |
| **Tasks** / **Agent runs** | `task_count` / `agent_run_count`            | How many tasks were active and how many agent turns ran in the window.         |

In Explore, the metric selector switches between **Credits**, **Runtime**, and **Tokens**. Tokens are not attributable per VM size, so the Tokens metric is unavailable when grouping by VM size.

## Group-bys

Explore pivots the data along one dimension at a time. Group by:

| Group by    | Pivots on                                                                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Project** | The project each task belongs to (default).                                                                                                             |
| **Agent**   | The coding [agent](/concepts/agents-and-models) (Codex, Claude Code, OpenCode, Cursor).                                                                 |
| **Model**   | The model the agent ran, scoped to its agent.                                                                                                           |
| **VM size** | The [runtime class](/concepts/pricing-and-tiers) (small, medium, large, xl). Carries runtime and credits only — tokens have no per-VM-size attribution. |
| **Status**  | The task [display status](/concepts/tasks-and-lifecycle) (running, awaiting\_input, awaiting\_ci, merged, unmerged, errored, archived).                 |
| **None**    | No pivot — shows the per-task ledger instead of a group table.                                                                                          |

The grouped table is interactive: clicking a row drills down one level (project → agent → model, or status/VM-size → the filtered ledger), narrowing the filters as it goes.

## Per-task ledger

Group by **None** to see the paginated task ledger — one row per task with its credits, runtime, tokens, status, project, agent, model, PR number, and hardware. Sort by any of:

| Sort field   | Column    |
| ------------ | --------- |
| `name`       | Task name |
| `started_at` | Started   |
| `credits`    | Credits   |
| `runtime`    | Runtime   |
| `tokens`     | Tokens    |

The ledger pages 25 rows at a time and defaults to sorting by credits, descending.

## Date range and filters

A date-range control offers presets (7d, 30d, 90d, this billing cycle) and a custom range up to 366 days. Multi-select filters narrow by project, agent, model, status, and VM size. Filters and the active range apply to both tabs.

## Export

In Explore, **Export CSV** downloads the current view. When grouped, it exports the complete group breakdown; with no grouping, it fetches every matching page of the task ledger, not just the visible page.

<Tabs>
  <Tab title="Web">
    Open **Settings → Usage**, choose **Overview** or **Explore**, then set the range, group-by, and filters.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    aether usage --from 2026-06-01 --to 2026-06-30 --group-by model
    ```

    See [`aether usage`](/cli/usage) for all flags.
  </Tab>

  <Tab title="API">
    The same data is available from the public endpoint. See [Get usage summary](/api-reference/v1/usage/get-usage-summary).
  </Tab>
</Tabs>