> ## 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.

# Cost Tracking

> How Pikarc calculates token costs and enforces budgets.

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](/api-reference/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`.

```bash theme={null}
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`.

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

<Note>
  Per-user daily budgets require the **Pro** plan or higher.
</Note>

### 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:

```bash theme={null}
# 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}'
```

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

## Viewing Usage

Check your current spend and usage breakdown via the [Usage API](/api-reference/usage):

```bash theme={null}
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.