Query usage with the CLI

mf usage reads token and cost records. Each command prints a table; add --json for reporting and monitoring, which prints the records as JSON. mf usage on its own runs mf usage summary.

Summary and time series

mf usage summary --from 2026-07-01T00:00:00Z --to 2026-08-01T00:00:00Z
mf usage summary --agent-id agt_xxx
mf usage timeseries --bucket day --from 2026-07-01T00:00:00Z

--from is inclusive and --to is exclusive. Filter by framework, runtime, agent, or chat session with --framework, --runtime-id, --agent-id, and --session-id.

Events and pagination

mf usage events --limit 200 --framework claude-code
mf usage events --cursor '<next-cursor>'

The cursor is opaque. Pass it back unchanged; do not parse or derive it.

Session and agent rankings

mf usage sessions --session-id ses_xxx
mf usage top-agents --limit 10

top-agents is account-wide and is denied for an agent-bound token. Use a human/account credential with the required permission. Missing or unknown cost data should remain unknown rather than being treated as zero.

See also

• Scripting with mf
• Manage automations with the CLI
• CLI command reference