Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pikarc.dev/llms.txt

Use this file to discover all available pages before exploring further.

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:
TokensRateCost
Input500$0.0000025/token$0.00125
Output100$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:
  1. Look up workspace daily spend from Redis (or Postgres fallback)
  2. Compare against workspace.daily_budget_usd
  3. If exceeded → DENY with WORKSPACE_DAILY_BUDGET_EXCEEDED
  4. Look up user daily spend from Redis (or Postgres fallback)
  5. Compare against workspace.user_daily_budget_usd
  6. If exceeded → DENY with USER_DAILY_BUDGET_EXCEEDED
After a step completes with token counts:
  1. Calculate cost_usd from model pricing
  2. Atomically increment workspace daily spend counter in Redis
  3. Atomically increment user daily spend counter in Redis
  4. 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.