Usage

See how many tokens and how much money your agents are spending — from your local machine.

See exactly where your tokens (and dollars) are going — no dashboard, no API key, no config.

praisonai usage reads the same local session store that praisonai session list uses and rolls it up per day, per model, or per project — or per tool, to show reliability and latency.

​

Quick Start

1. Run the default report

   Show the last 30 days grouped by day:

   praisonai usage
   

   Usage
   ┏━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┓
   ┃ Day        ┃  Tokens ┃    Cost ┃
   ┡━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━┩
   │ 2026-07-15 │   4,320 │ $0.0180 │
   │ 2026-07-18 │  12,500 │ $0.0512 │
   │ Total      │  16,820 │ $0.0692 │
   └────────────┴─────────┴─────────┘
   
2. Group by cost driver

   Find your most expensive model:

   praisonai usage --by model
   
3. See per-tool reliability

   praisonai usage --by tool
   

   Reports calls, success rate, average latency, and the last error for each tool used.

---

​

Choose Your View

Four groupings answer four different questions.

tool sorts by most-called first, so your busiest (or busiest-failing) tool rises to the top.

By day

Spot spend spikes over time. Rows sort chronologically.

By model

Find your most expensive model. Rows sort by highest spend first.

By project

Compare projects sharing one machine. Rows sort by highest spend first.

By tool

Spot flaky or slow tools. Rows sort by call count first.

---

​

Options

praisonai usage [--days N] [--by day|model|project|tool] [--project ID] [--json]

Option	Short	Type	Default	Description
--days	-d	int	30	Only include sessions updated in the last N days (0 = all time)
--by	-b	str	"day"	Group by day, model, project, or tool
--project	-p	str	(none)	Restrict to a specific project ID
--json	—	bool	False	Emit machine-readable JSON instead of a table

---

​

Per-Tool Reliability

praisonai usage --by tool reports per-tool call counts, success rate, average and last latency, and the last error — read from the local session store, same as every other grouping.

                                 Tool usage
┏━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Tool       ┃ Calls ┃ Success ┃ Avg ms ┃ Last ms ┃ Last error ┃
┡━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━┩
│ search     │     3 │  66.7%  │   200  │   200   │ timeout    │
│ write_file │     1 │ 100.0%  │     5  │     5   │ -          │
└────────────┴───────┴─────────┴────────┴─────────┴────────────┘

Column	Meaning
Tool	Tool name as the runtime saw it
Calls	How many times the tool was invoked
Success	Percentage of calls that returned without an error
Avg ms	Average execution time across all calls
Last ms	Latency of the most recent call
Last error	Last error message (truncated to 60 chars in the table, 500 in JSON)

Last ms and Last error are picked by when the tool itself last ran, not by when the session was last updated. If no tool calls are recorded, the command prints No tool usage recorded yet.

The tally counts tool outcomes that reach the AFTER_TOOL hook — which covers normalised tool failures (the common case). A raw exception that escapes the tool retry loop does not fire AFTER_TOOL and is not counted.

​

Python: read the same data with a hook

Prefer Python? The same per-call data is available via the AFTER_TOOL hook — no new API is needed.

from praisonaiagents.hooks import add_hook, HookEvent

def on_tool(data):
    print(data.tool_name, data.execution_time_ms, data.tool_error)

add_hook(HookEvent.AFTER_TOOL, on_tool)

The CLI tally reads exactly these three fields.

---

​

Common Patterns

Check last week only:

praisonai usage --days 7

Break a single project down by model:

praisonai usage --project my-app --by model

Pipe into jq to flag expensive rows:

praisonai usage --json | jq '.rows[] | select(.cost > 1)'

The JSON output shape:

{
  "by": "model",
  "days": 30,
  "project": null,
  "rows": [
    { "key": "gpt-4o",      "total_tokens": 12500, "cost": 0.0512 },
    { "key": "gpt-4o-mini", "total_tokens":  4320, "cost": 0.0180 }
  ],
  "total_tokens": 16820,
  "cost": 0.0692,
  "errors": []
}

The --by tool JSON shape:

{
  "by": "tool",
  "days": 30,
  "project": null,
  "rows": [
    {
      "tool": "search",
      "calls": 3,
      "successes": 2,
      "errors": 1,
      "success_rate": 0.6667,
      "avg_ms": 200.0,
      "last_ms": 200.0,
      "last_error": "timeout"
    }
  ],
  "errors": []
}

Tool mode omits the top-level total_tokens / cost fields — it reports outcomes, not spend.

Spot flaky or slow tools:

# Spot flaky tools over the last week
praisonai usage --by tool --days 7

# Find the slowest tool across all history
praisonai usage --by tool --days 0 --json | jq '.rows | sort_by(-.avg_ms) | .[0]'

# Alert on tool failure rate in CI
praisonai usage --by tool --json | jq '.rows[] | select(.success_rate < 0.9)'

---

​

How It Works

praisonai usage reads the on-disk session store — the same store surfaced by praisonai session list. No network calls, no configuration, no external observability platform.

With no --project, both the current-project store and the global default store are read. Rows keep their originating identity (current or global), and a session that appears in both stores is counted once.

Behaviour	What happens
--days 0	No time filter — includes every session
Empty store	Prints No usage recorded yet (no table)
Store read failure	Reports Usage may be incomplete: ... (or an errors array in --json) instead of returning zero
Invalid --by value	Exits with code 1 and prints --by must be one of: day, model, project, tool

Costs come from the existing per-run ModelPricing tracker — usage aggregates what was already recorded, it does not re-price.

---

​

Best Practices

Run a quick weekly check-in

Use --days 7 for a fast look at the current week before it grows into a surprise bill.

praisonai usage --days 7

Compare models before switching providers

Group by model to see which model drives your spend, then decide whether a cheaper one fits.

praisonai usage --by model

Alert on runaway spend in CI

Use --json in cron or CI and act on the numbers with jq.

praisonai usage --json | jq '.cost'

Spot flaky or slow tools before users notice

Run praisonai usage --by tool --days 7 as part of your weekly review. Rows are sorted by call count first, so the busiest tool is on top — and the Success column immediately shows which ones are quietly failing. Pipe --json into jq in CI to fail a build when any tool drops below your target success rate.

Remember it counts local spend only

Numbers reflect only what was recorded to the local session store. For team-wide totals across machines, use an observability integration such as Langfuse.

---

​

Related

Session

The session store this command reads from.

Traces

Richer per-trace inspection.

Cost Tracking

The in-run cost display this aggregates.

Metrics

Real-time token counters during a run.