aether usage - Aether

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.

Usage

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
`--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

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

# 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