Cost Tracking

Pikarc tracks costs at the step level using model pricing and token counts. These costs roll up into workspace and per-user daily budgets that are enforced in real time.

Cost Calculation

When the SDK reports token counts after a model call, the cost is calculated as:

cost_usd = prompt_tokens × input_cost_per_token
         + completion_tokens × output_cost_per_token

Pricing rates come from the Model Pricing configuration. If no pricing entry exists for a model, cost_usd remains null for that step.

Example

For a gpt-4o call with 500 prompt tokens and 100 completion tokens:

	Tokens	Rate	Cost
Input	500	$0.0000025/token	$0.00125
Output	100	$0.0000100/token	$0.00100
Total			$0.00225

Budget Enforcement

Workspace Daily Budget

Set daily_budget_usd on your workspace to limit total spend per day. When cumulative spend for the current day (UTC) reaches this limit, all subsequent runs and steps are denied with WORKSPACE_DAILY_BUDGET_EXCEEDED.

curl -X PATCH http://localhost:8000/v1/workspace/ \
  -H "Authorization: Bearer lg_..." \
  -H "Content-Type: application/json" \
  -d '{"daily_budget_usd": 100.0}'

Set to null to remove the limit.

User Daily Budget

Set user_daily_budget_usd to limit spend per SDK user per day. This is a uniform limit — all users share the same daily budget cap. When any user’s spend reaches the limit, their requests are denied with USER_DAILY_BUDGET_EXCEEDED.

curl -X PATCH http://localhost:8000/v1/workspace/ \
  -H "Authorization: Bearer lg_..." \
  -H "Content-Type: application/json" \
  -d '{"user_daily_budget_usd": 25.0}'

Per-user daily budgets require the Pro plan or higher.

How Budgets Reset

Daily budgets reset at midnight UTC. The Redis spend counters are keyed by date (YYYY-MM-DD) and expire automatically after 25 hours.

Enforcement Flow

When a run starts or a step is created, the guardrails engine checks budgets in this order:

Look up workspace daily spend from Redis (or Postgres fallback)
Compare against workspace.daily_budget_usd
If exceeded → DENY with WORKSPACE_DAILY_BUDGET_EXCEEDED
Look up user daily spend from Redis (or Postgres fallback)
Compare against workspace.user_daily_budget_usd
If exceeded → DENY with USER_DAILY_BUDGET_EXCEEDED

After a step completes with token counts:

Calculate cost_usd from model pricing
Atomically increment workspace daily spend counter in Redis
Atomically increment user daily spend counter in Redis
Store cost_usd on the step in Postgres

Setting Up Model Pricing

For cost tracking to work, you need to configure pricing for your models:

# GPT-4o
curl -X PUT http://localhost:8000/v1/model-pricing/gpt-4o \
  -H "Authorization: Bearer lg_..." \
  -H "Content-Type: application/json" \
  -d '{"input_cost_per_token": 0.0000025, "output_cost_per_token": 0.000010}'

# GPT-4o-mini
curl -X PUT http://localhost:8000/v1/model-pricing/gpt-4o-mini \
  -H "Authorization: Bearer lg_..." \
  -H "Content-Type: application/json" \
  -d '{"input_cost_per_token": 0.00000015, "output_cost_per_token": 0.0000006}'

The model string in your pricing config must match exactly what you pass to run.model_call(model=...).

Viewing Usage

Check your current spend and usage breakdown via the Usage API:

curl http://localhost:8000/v1/usage/summary \
  -H "Authorization: Bearer lg_..."

This returns today’s spend, 7-day and 30-day totals, plus breakdowns by model and by user. The dashboard also visualizes this data on the main page.

Getting Started

SDK

API Reference

Guides

Configuration

Cost Calculation

Example

Budget Enforcement

Workspace Daily Budget

User Daily Budget

How Budgets Reset

Enforcement Flow

Setting Up Model Pricing

Viewing Usage

​Cost Calculation

​Example

​Budget Enforcement

​Workspace Daily Budget

​User Daily Budget

​How Budgets Reset

​Enforcement Flow

​Setting Up Model Pricing

​Viewing Usage

Cost Calculation

Example

Budget Enforcement

Workspace Daily Budget

User Daily Budget

How Budgets Reset

Enforcement Flow

Setting Up Model Pricing

Viewing Usage