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

**Credits** are the VM-runtime figure. Tokens are reported for visibility and never charged to credits; calls on Aether inference are charged to the separate inference balance. See [billing and credits](/concepts/billing-and-credits).

## Usage

```bash theme={"dark"}
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={"dark"}
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={"dark"}
# 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
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.