> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.nozle.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Cost Models

> Define per-unit costs for margin calculation

Cost models tell Nozle what each unit of usage costs you. Without cost models, the margin engine can't calculate your AI spend.

## Cost model types

| Type        | Use case             | How it works                                                   |
| ----------- | -------------------- | -------------------------------------------------------------- |
| `per_unit`  | Fixed cost per event | Every event costs the same (e.g. \$0.03 per API call)          |
| `per_model` | LLM token pricing    | Different rates per model (GPT-4o costs more than GPT-4o-mini) |
| `tiered`    | Volume discounts     | Cost per unit changes at thresholds                            |

## Create a cost model (sk\_ key required)

### Per-model (recommended for LLM)

```bash theme={null}
curl -X POST https://api.nozle.app/api/v1/cost-models \
  -H "Authorization: Bearer sk_nozle_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "LLM Token Pricing",
    "metric_code": "llm_tokens",
    "cost_type": "per_model",
    "model_rates": {
      "gpt-4o": { "input": 250, "output": 1000 },
      "gpt-4o-mini": { "input": 15, "output": 60 },
      "gpt-4.1": { "input": 200, "output": 800 },
      "gpt-4.1-mini": { "input": 40, "output": 160 },
      "claude-sonnet-4-20250514": { "input": 300, "output": 1500 },
      "claude-haiku-4-20250414": { "input": 80, "output": 400 }
    }
  }'
```

Rates are in **cents per 1M tokens**. The margin engine calculates cost automatically when events arrive with `model`, `input_tokens`, and `output_tokens` properties.

### Per-unit

```bash theme={null}
curl -X POST https://api.nozle.app/api/v1/cost-models \
  -H "Authorization: Bearer sk_nozle_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Call Cost",
    "metric_code": "api_calls",
    "cost_type": "per_unit",
    "amount_cents": 3
  }'
```

### Tiered

```bash theme={null}
curl -X POST https://api.nozle.app/api/v1/cost-models \
  -H "Authorization: Bearer sk_nozle_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Volume Pricing",
    "metric_code": "api_calls",
    "cost_type": "tiered",
    "tier_mode": "SLAB",
    "tiers": [
      { "up_to": 10000, "unit_amount_cents": 5, "flat_amount_cents": 0 },
      { "up_to": 100000, "unit_amount_cents": 3, "flat_amount_cents": 0 },
      { "up_to": null, "unit_amount_cents": 1, "flat_amount_cents": 0 }
    ]
  }'
```

## List cost models

```bash theme={null}
curl https://api.nozle.app/api/v1/cost-models \
  -H "Authorization: Bearer sk_nozle_..."
```

## Delete a cost model

```bash theme={null}
curl -X DELETE https://api.nozle.app/api/v1/cost-models/{id} \
  -H "Authorization: Bearer sk_nozle_..."
```

## How it connects to margin

Once a cost model is configured, every usage event matching the `metric_code` is automatically enriched with cost data:

1. SDK sends `nozle.track(customerId, "llm_tokens", { model: "gpt-4o", input_tokens: 500, output_tokens: 200 })`
2. The margin engine looks up the cost model for `llm_tokens`
3. For `per_model` type: calculates `(500 × 250 + 200 × 1000) / 1,000,000 = $0.000325`
4. Stores revenue, cost, and margin in the margin events table
5. Dashboard shows per-customer, per-model, per-feature margin breakdown