Usage Reporting

Zero-config local token and cost reporting for PraisonAI sessions

See how many tokens and dollars your agents have spent — locally, with one command, no external service.

praisonai usage

Run praisonai at least once so a session exists — otherwise the report is empty.

​

Quick Start

1. See your spend

   praisonai usage
   
2. Change the grouping

   praisonai usage --by model
   praisonai usage --by project
   
3. Narrow the window or script it

   praisonai usage --days 7
   praisonai usage --json
   
4. See per-tool reliability

   praisonai usage --by tool
   

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

---

​

How It Works

The command reads the already-persisted total_tokens and cost fields on each session record in the local session store, filters by --days, groups by --by, and renders a table or JSON. No new data is written, no network calls, no configuration.

Behaviour	Detail
Two stores read	Without --project, both the current-project store and the global default store are read, tagged current / global.
De-duplication	Sessions shared across both stores are collapsed by session_id.
Bounded scan	Up to 100,000 sessions per store are read.
Cost source	The persisted cost uses the same ModelPricing table as praisonai tracker, so numbers match.

Cost values match praisonai tracker — both read from the same pricing reference.

---

​

Choosing --by

Pick the dimension that answers your question.

day sorts chronologically; model and project sort by highest token count first. tool sorts by most-called first, so your busiest (or busiest-failing) tool rises to the top.

---

​

Options

Option	Short	Type	Default	Values	Description
--days	-d	int	30	any int; 0 = all	Only include sessions updated in the last N days.
--by	-b	str	day	day | model | project | tool	Group rows by dimension. Invalid values exit 1.
--project	-p	str	None	any project id	Restrict to a specific project’s session store.
--json	—	bool	False	flag	Emit machine-readable JSON instead of a table.

An invalid --by value prints --by must be one of: day, model, project, tool and exits with code 1.

---

​

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.

---

​

Output Formats

Table

┌────────────┬────────┬─────────┐
│ Day        │ Tokens │ Cost    │
├────────────┼────────┼─────────┤
│ 2026-07-19 │ 12,345 │ $0.1234 │
│ Total      │ 12,345 │ $0.1234 │
└────────────┴────────┴─────────┘

Zero values render as -, and a final Total row sums the report.

JSON

{
  "by": "day",
  "days": 30,
  "project": null,
  "rows": [{"key": "2026-07-19", "total_tokens": 12345, "cost": 0.1234}],
  "total_tokens": 12345,
  "cost": 0.1234,
  "errors": []
}

JSON (--by tool)

{
  "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.

---

​

Empty Stores and Warnings

Empty and broken reports are always distinguishable.

• No sessions yet? The command prints No usage recorded yet and exits 0.
• A damaged or unreadable store surfaces as Usage may be incomplete: ... in table mode, or in the top-level errors array in JSON mode.

---

​

Best Practices

Alert on spend in CI

Wire praisonai usage --days 7 --json into a cron or CI job and alert if cost exceeds a threshold.

Find your most expensive model

Run praisonai usage --by model weekly to see which model your agents actually spend the most on.

Compare workspaces

Use praisonai usage --project <id> inside a workspace and praisonai usage --by project in the default shell to compare workloads.

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.

Script with jq

--json is stable for scripting — pipe into jq or a small dashboard rather than parsing the table.

---

​

Related

Token Usage Protocol

Wire custom sinks and queries (databases, dashboards)

Sessions

The store praisonai usage reads from

Cost Tracker

Per-run token and cost tracking