Usage - PraisonAI

See what you’ve spent — no dashboard, no API key, no setup. praisonai usage reads the token and cost totals PraisonAI already saves per session and rolls them up by day, model, or project — or reports per-tool reliability with --by tool.

Quick Start

See your spend

Run one line to see the last 30 days grouped by day.

praisonai usage

              Usage
┏━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┓
┃ Day        ┃ Tokens  ┃ Cost    ┃
┡━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━┩
│ 2026-07-19 │ 1,240   │ $0.0140 │
│ 2026-07-20 │ 3,980   │ $0.0320 │
│ Total      │ 5,220   │ $0.0460 │
└────────────┴─────────┴─────────┘

Group differently

Switch the grouping to see spend by model or by project.

praisonai usage --by model

Group by project (current vs global stores)

praisonai usage --by project

Last 7 days only

praisonai usage --days 7

A single project

praisonai usage --project my-app

Get JSON for scripts

Add --json for machine-readable output you can pipe to jq.

praisonai usage --json

See per-tool reliability

praisonai usage --by tool

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

This command reads data that praisonai run already saved to disk — no setup, no re-instrumentation, no external observability platform.

Choose Your Grouping

Pick the --by value that matches the question you’re asking. tool sorts by most-called first, so your busiest (or busiest-failing) tool rises to the top.

How It Works

praisonai usage reads the same session files that praisonai session list shows — nothing new is written, no external service is contacted.

Source	What it contributes
Current-project session store	Sessions from the project you’re in — labelled `current` under `--by project`.
Global default session store	Sessions from the global store — labelled `global` under `--by project`.
`--project <id>`	Restricts to exactly that project’s store; its own ID becomes the sole `project` label.

When --project is omitted, both stores are scanned separately and session ids shared across them are de-duplicated (the current-project store wins). Each store is scanned up to 100,000 sessions to keep memory predictable — realistic stores are never truncated.

Behaviour	Detail
Time window	`--days` filters on `updated_at`; values without a timezone are treated as UTC
Sorting	`--by day` is chronological; `--by model` / `--by project` sort by highest tokens first
Grouping keys	Unknown model → `unknown`; unparseable date → `unknown`; empty project → `current`
Total row	The table always appends a `Total` row
Zero values	Render as `-`; tokens are comma-formatted; cost is `$X.XXXX`

Options

Every option is optional — praisonai usage with no flags reports the last 30 days by day.

Option	Short	Type	Default	Description
`--days`	`-d`	`int`	`30`	Only include sessions updated in the last N days. `0` = no time filter (include all).
`--by`	`-b`	`str`	`"day"`	Group by: `day`, `model`, `project`, or `tool`. Any other value exits with an error.
`--project`	`-p`	`str`	`None`	Restrict to a specific project ID (reads only that project’s scoped store).
`--json`		`bool`	`False`	Emit machine-readable JSON (also auto-enabled by the CLI’s global JSON output mode).

--by day sorts chronologically (ascending); --by model and --by project sort by tokens descending (highest spend first); --by tool sorts by call count descending, then alphabetically.

JSON output shape

--json emits a stable object you can pipe into dashboards or cron jobs.

praisonai usage --by day --days 30 --json

{
  "by": "day",
  "days": 30,
  "project": null,
  "rows": [
    {"key": "2026-07-15", "total_tokens": 12340, "cost": 0.043},
    {"key": "2026-07-18", "total_tokens": 5220, "cost": 0.014}
  ],
  "total_tokens": 17560,
  "cost": 0.057,
  "errors": []
}

With --by tool, each row describes a tool instead of a spend bucket:

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

Table: No usage recorded yet
JSON: {"rows": [], "total_tokens": 0, "cost": 0.0, ...}
--by tool table: No tool usage recorded yet

Store errors

A missing or damaged store is non-fatal. Table mode prints Usage may be incomplete: <reason> as a warning; JSON mode exposes the reasons under errors. The command still exits 0 and returns whatever it could read — a broken store is never silently reported as empty. An invalid --by value exits 1 with --by must be one of: day, model, project, tool.

Common Patterns

Practical one-liners for everyday reviews.

# Weekly review by model
praisonai usage --days 7 --by model

# CI cost snapshot
praisonai usage --json | jq '.cost'

# Full history by project (no time filter)
praisonai usage --days 0 --by project

# Export 90 days to CSV
praisonai usage --days 90 --by day --json | jq '.rows[] | [.key, .total_tokens, .cost] | @csv' -r > usage.csv

# 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)'

Grouping Modes

Mode	Sorts by	Use it to
`--by day`	Chronological	See a spend trend over time.
`--by model`	Highest spend first	Find which model costs the most.
`--by project`	Highest spend first	Compare spend across workspaces.
`--by tool`	Most calls first	Spot flaky or slow tools.

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.

Best Practices

Find your most expensive models

Run praisonai usage --by model — models are sorted by highest token count first, so the biggest spenders appear at the top.

Report across all history

Use praisonai usage --days 0 to disable the time filter and aggregate every session on disk, not just the last 30 days. Use this sparingly on very large session directories, since it scans up to 100,000 records per store.

Feed usage into scripts

praisonai usage --json emits a stable shape (by, days, project, rows, total_tokens, cost, errors) that is safe to parse in CI or dashboards. The global JSON output mode auto-enables JSON, so scripts running under it get machine-readable output without passing --json explicitly.

Trust the numbers

Watch for Usage may be incomplete warnings. They mean a store could not be read fully — check filesystem permissions on the session store path and look for corrupt records. The totals shown exclude that store rather than silently reporting zero. In --json mode the same reasons appear in the errors array.

Attribute cost per workspace

Combine --project my-app with --by model to see which model drives spend inside one project.

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

Script budget checks

Pipe --json output to jq in CI to fail a build when spend crosses a threshold.

praisonai usage --json | jq 'if .cost > 5 then error("over budget") else .cost end'

Missing cost? Check pricing coverage

Cost only appears for models present in the default pricing table. See Cost Tracking to add custom pricing.

Read current vs global buckets correctly

Without --project, --by project splits usage into a current bucket (this project’s store) and a global bucket (the default store). Shared session IDs appear once. Pass --project my-app to report a single project only.

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.

Cost Tracking

Per-run and per-session cost source

Session

The underlying session store

Tracker

Per-run execution tracker

Metrics

Performance metrics

​Quick Start

​Choose Your Grouping

​How It Works

​Options

​JSON output shape

​Empty output

​Store errors

​Common Patterns

​Grouping Modes

​Per-Tool Reliability

​Best Practices

​Related

Cost Tracking

Session

Tracker

Metrics

Quick Start

Choose Your Grouping

How It Works

Options

JSON output shape

Empty output

Store errors

Common Patterns

Grouping Modes

Per-Tool Reliability

Best Practices

Related