How Costs Are Calculated

Cost is based on:

1. Token usage — The number of prompt (input) and completion (output) tokens consumed
2. Model pricing — The per-token price for the specific LLM model used
3. Automatic aggregation — Span-level costs are rolled up to execution and workspace levels

The formula is:

cost = (prompt_tokens * input_price_per_token) + (completion_tokens * output_price_per_token)

PromptRails keeps model pricing metadata for supported providers and uses it to estimate costs automatically.

Per-Execution Cost Breakdown

Every execution includes total cost and token usage:

execution = client.executions.get(execution_id="your-execution-id")
 
print(f"Total Cost: ${execution.cost:.6f}")
print(f"Token Usage: {execution.token_usage}")
print(f"Duration: {execution.duration_ms}ms")

For runs that delegate to sub-agents or fan out across workflow nodes, the cost rolls up over the whole execution tree — the sum of the LLM spans in the run and all of its children.

Per-Span Cost Analysis

Drill down into individual spans to see cost at the LLM call level:

traces = client.traces.list(execution_id="your-execution-id", kind="llm")
 
for span in traces.data:
    print(f"Model: {span.model_name}")
    print(f"  Prompt tokens: {span.prompt_tokens or 0}")
    print(f"  Completion tokens: {span.completion_tokens or 0}")
    print(f"  Cost: ${span.cost or 0:.6f}")
    print(f"  Duration: {span.duration_ms}ms")
    print("---")

This is valuable for identifying which step in a complex pipeline is the most expensive.

Token Usage Tracking

Token usage is tracked with three metrics:

Token counts are provided by the LLM provider and recorded with each LLM span.

Workspace-Wide Cost Summary

Cost, tokens, and latency roll up on traces. Get aggregated statistics across your workspace with traces.get_summary:

summary = client.traces.get_summary()
 
print(f"Total Cost: ${summary.total_cost:.2f}")
print(f"Total Traces: {summary.total_traces}")
print(f"Total Tokens: {summary.total_tokens}")
print(f"Avg Duration: {summary.avg_duration_ms:.0f}ms")

TraceSummary reports total_traces, total_tokens, total_cost, avg_duration_ms, error_count, unique_models, and unique_sessions.

Per-Agent and Filtered Cost Analysis

traces.get_summary accepts the same filters as traces.list plus date_from / date_to, status, level, and model_name. Pass agent_id to break spend down by agent, or session_id / execution_id to scope a single run:

agent_costs = client.traces.get_summary(agent_id="your-agent-id")
 
print(f"Agent Total Cost: ${agent_costs.total_cost:.2f}")
print(f"Agent Traces: {agent_costs.total_traces}")
print(f"Agent Tokens: {agent_costs.total_tokens}")

LLM Model Pricing

PromptRails maintains pricing information for all supported LLM models. Prices are stored as cost per token (or per 1K/1M tokens depending on the model) and are used for automatic cost calculation.

Supported providers and their models include:

Cached input tokens (prompt-cache read hits) are billed at the model’s discounted cached-input rate when configured, so prices reflect the lower cost providers charge for cached prompt prefixes.