Cost Tracking

Real-time token usage and cost monitoring for AI operations

Cost Tracking

PraisonAI CLI provides comprehensive cost tracking to help you monitor token usage and expenses across your AI coding sessions. Know exactly what you’re spending in real-time.

See Usage for cross-session aggregate reporting.

Overview

The cost tracking system monitors:

• Token usage - Input, output, and cached tokens
• Cost calculation - Real-time cost based on model pricing
• Session statistics - Aggregated stats across requests
• Model breakdown - Usage per model

Per-session totals

After every praisonai run with an active session, a compact footer prints to stdout:

praisonai run "Refactor auth.py" --session refactor
# → 1,240 in / 3,980 out · $0.0140

praisonai session list
# → Tokens/Cost columns now populated

praisonai run "and add tests" --continue --session refactor
# → totals accumulate, not reset

Totals persist in session metadata and survive resume. Multi-model runs are priced per-model — each call is priced against its own model via get_pricing(model), then summed. The footer is silenced under --output json.

To aggregate these persisted totals across many sessions — by day, model, or project — see Usage.

---

Quick Start

# View costs during interactive session
>>> /cost

# Or use the Python API
from praisonai.cli.features import CostTrackerHandler

tracker = CostTrackerHandler()
tracker.initialize()
tracker.track_request("gpt-4o", input_tokens=1000, output_tokens=500)
print(f"Total cost: ${tracker.get_cost():.4f}")

Supported Models

Cost tracking supports 18+ models with accurate pricing:

OpenAI Models

Model	Input (per 1M)	Output (per 1M)
gpt-4o	$2.50	$10.00
gpt-4o-mini	$0.15	$0.60
gpt-4-turbo	$10.00	$30.00
o1	$15.00	$60.00
o1-mini	$3.00	$12.00
o3-mini	$1.10	$4.40

Anthropic Models

Model	Input (per 1M)	Output (per 1M)
claude-3-5-sonnet	$3.00	$15.00
claude-3-opus	$15.00	$75.00
claude-3-haiku	$0.25	$1.25

Google Models

Model	Input (per 1M)	Output (per 1M)
gemini-2.0-flash	$0.10	$0.40
gemini-1.5-pro	$1.25	$5.00
gemini-1.5-flash	$0.075	$0.30

Python API

Basic Tracking

from praisonai.cli.features import CostTrackerHandler

# Initialize tracker
handler = CostTrackerHandler()
tracker = handler.initialize(session_id="my-session")

# Track a request
stats = handler.track_request(
    model="gpt-4o",
    input_tokens=1000,
    output_tokens=500,
    cached_tokens=200,
    duration_ms=1500.0
)

# Get totals
print(f"Total tokens: {handler.get_tokens()}")
print(f"Total cost: ${handler.get_cost():.4f}")

Session Statistics

# Get detailed summary
summary = handler.get_summary()

print(f"Session ID: {summary['session_id']}")
print(f"Total requests: {summary['total_requests']}")
print(f"Input tokens: {summary['total_input_tokens']}")
print(f"Output tokens: {summary['total_output_tokens']}")
print(f"Cached tokens: {summary['total_cached_tokens']}")
print(f"Total cost: ${summary['total_cost']:.4f}")
print(f"Avg cost/request: ${summary['avg_cost_per_request']:.4f}")

Tracking from LLM Responses

from praisonai.cli.features.cost_tracker import CostTracker

tracker = CostTracker()

# Track from OpenAI-style response
response = openai_client.chat.completions.create(...)
tracker.track_from_response("gpt-4o", response)

# Track from dict response
response_dict = {
    "usage": {
        "prompt_tokens": 500,
        "completion_tokens": 200
    }
}
tracker.track_from_response("gpt-4o", response_dict)

Export Session Data

import json

# Export to JSON
json_str = tracker.export_json()
data = json.loads(json_str)

# Structure:
# {
#   "session": {
#     "session_id": "abc123",
#     "start_time": "2024-01-01T12:00:00",
#     "total_requests": 10,
#     "total_cost": 0.0425,
#     ...
#   },
#   "requests": [
#     {"model": "gpt-4o", "input_tokens": 1000, ...},
#     ...
#   ]
# }

# Save to file
with open("session_costs.json", "w") as f:
    f.write(json_str)

CLI Integration

Interactive Mode

praisonai chat

>>> Help me refactor this code
[AI responds...]

>>> /cost
╭─────────────────────────────────────╮
│           Session Stats             │
├─────────────────────────────────────┤
│ Session: abc12345                   │
│ Duration: 125.3s                    │
│ Requests: 3                         │
│                                     │
│ Tokens:                             │
│   Input:  2,500                     │
│   Output: 800                       │
│   Total:  3,300                     │
│   Cached: 500                       │
│                                     │
│ Cost: $0.0125                       │
│ Avg per request: $0.0042            │
│                                     │
│ Models used:                        │
│   gpt-4o: 2 requests                │
│   gpt-4o-mini: 1 request            │
╰─────────────────────────────────────╯

Token Breakdown

>>> /tokens
╭─────────────────────────────────────╮
│          Token Breakdown            │
├─────────────────────────────────────┤
│ Input tokens:  2,500 (75.8%)        │
│ Output tokens: 800 (24.2%)          │
│ Cached tokens: 500 (saved)          │
│                                     │
│ Context window: 128,000             │
│ Used: 2.6%                          │
╰─────────────────────────────────────╯

Cost Calculation

How Costs Are Calculated

from praisonai.cli.features.cost_tracker import ModelPricing

# Get pricing for a model
pricing = ModelPricing(
    model_name="gpt-4o",
    input_price_per_1m=2.50,
    output_price_per_1m=10.00
)

# Calculate cost
input_tokens = 1000
output_tokens = 500

cost = pricing.calculate_cost(input_tokens, output_tokens)
# (1000 / 1,000,000 * 2.50) + (500 / 1,000,000 * 10.00)
# = 0.0025 + 0.005
# = $0.0075

Custom Pricing

Add pricing for custom or new models:

from praisonai.cli.features.cost_tracker import ModelPricing, DEFAULT_PRICING

# Add custom model pricing
DEFAULT_PRICING["my-custom-model"] = ModelPricing(
    model_name="my-custom-model",
    input_price_per_1m=1.00,
    output_price_per_1m=2.00,
    context_window=32000
)

# Now tracking will use this pricing
tracker.track_request("my-custom-model", 1000, 500)

Per-session persistence

Usage is now accumulated into the session metadata at ~/.praisonai/sessions/<id>.json under a usage blob, so costs persist across terminal sessions and are visible in praisonai session list.

How it works:

• After each run, accumulate_session_usage merges the new per-call usage from praisonaiagents.telemetry.token_collector into the session file.
• The token_collector is then reset to avoid double-counting on the next run.
• Pricing comes from cli/features/cost_tracker.get_pricing(model) — the same model price table used by /cost.
• Resuming with praisonai run --continue or praisonai run --session <id> rehydrates RehydratedSession.usage so the cumulative totals continue accumulating.

Sessions stored in the global store (created via the gateway or TUI) are handled transparently — _resolve_usage_store prefers whichever record already carries usage, so resuming a globally-stored session keeps accumulating into the original record.

Persisted usage blob keys:

Key	Type	Notes
input_tokens	int	Cumulative prompt tokens
output_tokens	int	Cumulative completion tokens
cached_tokens	int	Cumulative cached / prefix-hit tokens (when the provider reports them)
total_tokens	int	input + output (cached not double-counted); mirrored to flat total_tokens on session metadata
cost	float	USD; mirrored to flat cost on session metadata
requests	int	Count of agent.start() runs that produced usage

# View current session costs
praisonai session list

ID         Name            Status   Events  Tokens   Cost     Updated
abc12345   research-bot    active   12      12,345   $0.0140  2026-06-29 23:48 UTC

Cross-link: see Session for the full session list column reference and Run for the per-run usage footer.

Scheduler Integration

AgentScheduler and AsyncAgentScheduler price every run through ModelPricing (since PR #2171). Any model you register here becomes spendable from the scheduler’s max_cost brake:

from praisonai.cli.features.cost_tracker import ModelPricing, DEFAULT_PRICING
from praisonai.scheduler import AsyncAgentScheduler

DEFAULT_PRICING["my-org/custom-llm"] = ModelPricing(
    model_name="my-org/custom-llm",
    input_price_per_1m=0.80,
    output_price_per_1m=2.40,
    context_window=32000,
)

scheduler = AsyncAgentScheduler(agent, task="Hourly digest", max_cost=5.00)

Models that are not in DEFAULT_PRICING are priced at $0 — they still run, but total_cost_usd will under-report and the max_cost brake won’t trip. See Async Agent Scheduler for the full budget pattern.

Real-Time Monitoring

Display During Operations

from praisonai.cli.features.cost_tracker import CostTracker

tracker = CostTracker()

# After each request, show running total
def on_request_complete(model, input_tokens, output_tokens):
    stats = tracker.track_request(model, input_tokens, output_tokens)
    print(f"Request cost: ${stats.cost:.4f}")
    print(f"Session total: ${tracker.get_total_cost():.4f}")

Budget Alerts

BUDGET_LIMIT = 1.00  # $1.00

def check_budget():
    current_cost = tracker.get_total_cost()
    if current_cost > BUDGET_LIMIT:
        print(f"⚠️ Budget exceeded! Current: ${current_cost:.2f}")
        return False
    elif current_cost > BUDGET_LIMIT * 0.8:
        print(f"⚠️ 80% of budget used: ${current_cost:.2f}")
    return True

Session Management

Multiple Sessions

# Create separate trackers for different tasks
refactor_tracker = CostTracker(session_id="refactor-task")
test_tracker = CostTracker(session_id="test-generation")

# Track separately
refactor_tracker.track_request("gpt-4o", 2000, 1000)
test_tracker.track_request("gpt-4o-mini", 500, 200)

# Compare costs
print(f"Refactoring: ${refactor_tracker.get_total_cost():.4f}")
print(f"Testing: ${test_tracker.get_total_cost():.4f}")

End Session

# End session and get final stats
final_stats = tracker.end_session()

print(f"Session ended at: {final_stats.end_time}")
print(f"Total duration: {final_stats.duration_seconds:.1f}s")
print(f"Final cost: ${final_stats.total_cost:.4f}")

Best Practices

Cost Optimization

1. Use appropriate models - gpt-4o-mini for simple tasks
2. Monitor token usage - Check /tokens regularly
3. Enable caching - Reduces input token costs
4. Batch operations - Fewer requests = lower overhead

Tracking Tips

1. Name sessions - Use descriptive session IDs
2. Export regularly - Save session data for analysis
3. Set budgets - Implement budget alerts
4. Review by model - Identify expensive operations

Environment Variables

# Set default budget limit
export PRAISONAI_BUDGET_LIMIT=10.00

# Enable cost display after each request
export PRAISONAI_SHOW_COSTS=true

# Custom pricing file
export PRAISONAI_PRICING_FILE=/path/to/pricing.json

Aggregate reporting: praisonai usage

The per-session totals persisted here feed the praisonai usage report, which aggregates spend across sessions by day, model, or project.

# Last 30 days, grouped by day
praisonai usage

# This week, by model
praisonai usage --days 7 --by model

See Usage for the full command reference, grouping options, and JSON output shape.

Related Features

• Usage - Aggregate spend/token reporting across sessions
• Slash Commands - Use /cost command
• Metrics - Detailed performance metrics
• Telemetry - Usage analytics
• Session - Per-session token and cost columns in session list
• Run - Per-run usage footer after each prompt
• Usage - Cross-session aggregate token and cost reporting