> ## 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.

# aether usage

> Show a credits, tokens, and VM-uptime usage summary

Show a usage summary for a time range: total credits, agent runs, tokens in and out, and VM uptime, with an optional breakdown group and a top-tasks ledger.

Aether bills on VM runtime, so **credits** are the figure that maps to cost. Tokens are reported for visibility but never billed. See [billing and credits](/concepts/billing-and-credits).

## Usage

```bash theme={null}
aether usage [flags]
```

With no `--from`/`--to`, the range defaults to the last 30 days.

## Flags

| Flag           | Default     | Description                                                                  |
| -------------- | ----------- | ---------------------------------------------------------------------------- |
| `--from`       | 30 days ago | Start time (RFC3339, or a date the API accepts)                              |
| `--to`         | now         | End time (RFC3339, or a date the API accepts)                                |
| `--project-id` |             | Filter by project ID or [prefix](/cli/overview#resolving-ids-short-prefixes) |
| `--agent-type` |             | Filter by agent type                                                         |
| `--model`      |             | Filter by model                                                              |
| `--group-by`   | `project`   | Breakdown group: `project`, `agent`, `model`, `vm_size`, `status`, or `none` |
| `--task-limit` | `10`        | Number of tasks to include in the ledger                                     |

## Output

```bash theme={null}
aether usage
```

```
Usage (2026-05-31T00:00:00Z to 2026-06-30T00:00:00Z)
  Tasks:        42
  Agent runs:   58
  Credits used: 1240.50
  Tokens in:    8421003
  Tokens out:   1903442
  Total tokens: 10324445
  VM uptime:    20h 41m

By project:
  GROUP            CREDITS   TOKENS      VM UPTIME   TASKS
  my-app           980.25    7100234     16h 12m     31
  backend-api      260.25    3224211     4h 29m      11

Top tasks:
  ID         TASK                    PROJECT       CREDITS   TOKENS
  a1b2c3d4   Fix the login bug       my-app        42.10     210334
  e5f6g7h8   Add dark mode           my-app        38.75     185221
```

The breakdown table reflects `--group-by`. With `--group-by vm_size` the tokens column is omitted, because tokens are not attributed per VM size. Use `--group-by none` to skip the breakdown.

## Examples

```bash theme={null}
# This month, broken down by model
aether usage --from 2026-06-01 --group-by model

# One project, agent breakdown, more tasks in the ledger
aether usage --project-id a1b2c3d4 --group-by agent --task-limit 25

# Machine-readable output
aether usage --json
```