Cost & model pricing

Every dollar figure in Neens — the Spend measure on a dashboard, the Cost column on the Traces list, the cost delta on a pre-prod comparison — is computed from the token counts your traces already carry, multiplied by a price for that specific model. This page explains where those prices come from, why some models are deliberately shown as unpriced rather than guessed at, and how to enter your own negotiated or self-hosted rates.

At a glance

How Neens computes cost

Cost is derived, never stored. There is no cost column on a trace waiting to be read — Neens computes the number at query time, every time:

1. Your traces record input and output token counts per span (and roll them up per trace), plus the model each model call used. Those come straight from your instrumentation — see Send traces.
2. At read time, Neens sums tokens grouped by model, resolves each model against the price table, and multiplies.

So a trace on claude-sonnet-5 with 12,000 input and 3,000 output tokens costs:

(12,000 / 1,000,000) × $3.00   = $0.036   input
 (3,000 / 1,000,000) × $15.00  = $0.045   output
                                 -------
                                 $0.081

Two consequences worth internalizing:

• Correcting a price corrects history immediately. Nothing was baked in at ingest, so entering a rate today makes every existing trace show the right number (subject to effective dates — a price change does not rewrite spend from before the change).
• One price table, everywhere. The per-trace estimate and the aggregate roll-up resolve through the same table, so a trace’s Cost and the dashboard Spend it contributes to can never disagree.

The surfaces cost feeds

Where prices come from

A price is a row in a table, not a constant in the product: it names a model, carries input, cached-input, and output rates in $/MTok, and is stamped with an effective date and a named source. Every price you see in Neens is in one of three states, and the UI labels which:

How a model resolves to a price

For each model Neens sees, it looks for a price in this order — and within each step, your rate beats the shipped list price. Note that the steps are tried in order: an exact list price is reached before any family-prefix rate, including one of yours, so state your override against the exact model id you run rather than a family prefix:

A model with no name at all (spans that never recorded gen_ai.request.model, gen_ai.response.model, or llm.model_name) is always unpriced, and appears in the unpriced list under an empty name. If you see that, the fix is instrumentation, not pricing — see Send traces.

Unpriced is a real state, not a bug

This is deliberate, and it is the single most important thing to understand about cost in Neens:

• An unpriced model contributes $0 to the total — it is excluded, not estimated.
• Its tokens are still counted and reported separately, so you can see exactly how much traffic is missing a price.
• Every dollar figure that includes unpriced traffic is labelled partial, with the number of unpriced models: ⚠ partial · 2 models unpriced. Its ⓘ names the models and links to Settings → Model pricing — see Fix a spend figure that says partial.
• A single unpriced value renders as —, never $0.00, so “we don’t know” never masquerades as “it was free”.

Aggregate responses carry the partial state as machine-readable metadata alongside the value, so dashboards, alerts, and the digest all surface the same caveat:

"pricing": {
  "partial": true,
  "unpricedModels": ["gpt-4o", ""],
  "unpricedInputTokens": 91000,
  "unpricedOutputTokens": 12000,
  "version": "42:2026-07-26T00:00:00Z"
}

Fix a spend figure that says partial

A spend figure reads partial when some traces in the window ran on a model with no rate. This section is the whole fix, end to end: what the label means, how to find out which models are unpriced, and how to price them. It takes about a minute per model, and you do it once per model — not once per dashboard.

Where you’ll see the badge

The badge sits next to the figure it qualifies, so the caveat travels with the number:

In dense chrome — a table cell, a graph footer — it renders compactly as partial (2); on a headline tile it renders in full as ⚠ partial · 2 models unpriced. When the backend flags the window as partial without enumerating the models (the Agent Map payload does), it says ⚠ partial · some models unpriced rather than inventing a count.

Read the popover — it names the models

Every badge carries an ⓘ. Hover it to read it, click it to pin it open so you can move the pointer onto the contents, and Escape or a click outside dismisses it. It’s a real button, so you can also reach it with Tab and open it from the keyboard.

Pinning matters because the popover is not just an explanation — it contains the link you need:

Partial spend Some traces in this window ran on a model with no rate. Their tokens are excluded from the total rather than priced at a guess, so real spend is higher than shown. Unpriced models: gpt-4o, llama-3.3-70b-instruct Set prices in Settings → Model pricing (a link)

That model list is the answer to “which ones?”, and the link goes straight to /settings?tab=pricing. A model that recorded no name at all is listed as (unknown model) — that one is an instrumentation fix, not a pricing one.

Then price them

The same fix, from the API

If you’d rather not click, GET /model-prices/observed gives you the identical list — every model your spans carried over the window, with priced: false on the ones making figures partial — and POST /model-prices sets a rate. Both are covered in Set rates from the API. Watching unpricedCount in CI is the durable version of this fix: it fails the day someone routes traffic to a model you haven’t priced, instead of the day someone notices a dashboard looks low.

Which models ship priced

The shipped catalogue is deliberately small: the Anthropic family, and the two gpt-oss local models at $0. Everything else is unpriced until you say otherwise — Neens only ships a price it can date, name a source for, and stand behind.

Anthropic — priced

The Anthropic family ships with dated list prices (source anthropic-list-2026-07-01, effective 2026-07-01), in $/MTok:

Plus three family fallback rows so an unrecognized dated snapshot still prices sanely: claude-opus- → $5 / $0.50 / $25, claude-sonnet- → $3 / $0.30 / $15, claude-haiku- → $1 / $0.10 / $5.

gpt-oss — priced at $0

Exactly two open-weight ids ship with a price: gpt-oss:20b and gpt-oss:120b, at $0.00 per million tokens, source self-hosted-zero-cost.

That is not “unknown” — it is a real, deliberate price. These are local-first models: they run on hardware you already pay for, so you’re billed for GPU compute and hours, not for tokens. Attaching a per-token price to them produces a number with no relationship to any invoice you will ever receive.

Everything else — unpriced on purpose

Every other model resolves to unpriced out of the box. That covers two groups, for two closely related reasons.

Third-party hosted models — GPT, Gemini, and friends. gpt-4o, gpt-4o-mini, gemini-2.5-pro and their siblings ship with no price. We will not state a third-party list price we cannot date and verify, and we especially will not ship one that quietly drifts out of date while your finance dashboard keeps reporting it as fact. Third-party pricing also varies by tier, region, batch mode, and contract — the number you are billed is genuinely not knowable from here.

Open-weight models beyond gpt-oss — Llama, Qwen, Mistral, Mixtral, DeepSeek, Phi, Gemma. llama-3.3-70b-instruct, mistral-large-latest, deepseek-chat, gemma-3-27b-it, phi-4, qwen2.5:14b and the rest are unpriced, deliberately — Neens does not blanket them at $0.

The reason is specific: the same model name can be free or expensive, and the model string alone doesn’t say which. mistral-large-latest might be running on your own GPUs (genuinely $0) or through Mistral’s La Plateforme, Bedrock, Together, Fireworks, or Groq — where every token is invoiced. A blanket $0 would silently price real, billed spend at nothing.

The remedy is one action, either way, and both answers are honest:

• Self-hosting Llama on your own GPUs? Set it to 0 once in Settings → Model pricing. It’s a real price, it sticks, and you never think about it again.
• Paying Together, Bedrock, Groq, or DeepSeek per token? Enter the rate off your invoice, once. Now your dashboards show what you’re actually spending.

Until you do, those models’ tokens are counted but contribute $0, and every spend figure that includes them is labelled partial — so the gap is visible rather than silent. Follow Set your own rate below; it takes about a minute per model.

Set your own rate

Settings → Model pricing is the admin surface. The table lists Model · Provider · Input · Cached · Output · Source, with the models you actually run listed first — including unpriced ones, each with a Set price button.

Set rates from the API

Every Settings action has a REST equivalent, so rates can live in your IaC repo or be applied from a CI job. Routes are available bare and under the canonical /api/ prefix; use /api/ for anything programmatic. Reads need any read-capable credential (a nk_live_ agent key works); writes need an admin-role credential — an admin’s session, or a nk_live_ agent key created with the admin role. This is not the operator nk_admin_ control-plane key, which carries no agent scope. The $NEENS_API_KEY in the examples below is an admin-role agent key.

Which models am I running, and which are unpriced?

GET /model-prices/observed is the “state of the world” call: the distinct models actually seen in your agent’s spans over a window, joined against the resolved price table.

curl -G https://your-neens-host/api/model-prices/observed \
  -H "Authorization: Bearer nk_live_your_key_here" \
  --data-urlencode "range=30d"

{
  "models": [
    {
      "model": "gpt-oss:20b",
      "priced": true,
      "matchedBy": "exact",
      "provenance": "platform",
      "effectiveFrom": "2026-07-01",
      "source": "self-hosted-zero-cost",
      "inputPerMillion": 0.0,
      "cachedInputPerMillion": null,
      "outputPerMillion": 0.0,
      "inputTokens": 1204000,
      "outputTokens": 88000,
      "spendUsd": 0.0,
      "priceId": "mp-platform-gpt-oss-20b-2026-07-01"
    }
  ],
  "unpricedCount": 2,
  "version": "42:2026-07-26T00:00:00Z"
}

unpricedCount is the number to watch: anything above zero means your spend figures are partial. A nightly CI check that fails when unpricedCount > 0 is a cheap way to keep a new model from silently landing outside your cost reporting.

Set a rate

curl -X POST https://your-neens-host/api/model-prices \
  -H "Authorization: Bearer $NEENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "gpt-4o",
    "provider": "openai",
    "displayName": "GPT-4o",
    "inputPerMillion": 1.88,
    "cachedInputPerMillion": 0.94,
    "outputPerMillion": 7.5,
    "effectiveFrom": "2026-07-01",
    "notes": "committed-use discount"
  }'

Returns 201 with the created row. Re-running the exact same call is a no-op upsert, not an error — so re-applying your pricing manifest on every deploy is safe.

Effective dates and historical accuracy

Every price row carries a window: effectiveFrom (inclusive) and effectiveTo (exclusive, empty = still current). A trace is costed at the price that was in force when it ran — not at today’s price.

That means a price change never retroactively rewrites last quarter’s spend. Your Q3 number stays your Q3 number after you renegotiate in Q4.

Worked example

You run claude-sonnet-5 on the shipped list price of $3.00 / $15.00, effective 2026-07-01. On 1 September you sign a committed-use agreement at 20% off, so you post your rate:

curl -X POST https://your-neens-host/api/model-prices \
  -H "Authorization: Bearer $NEENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "claude-sonnet-5",
    "provider": "anthropic",
    "inputPerMillion": 2.4,
    "outputPerMillion": 12.0,
    "effectiveFrom": "2026-09-01",
    "notes": "committed-use agreement, 20% off list"
  }'

From then on, the same 12,000-in / 3,000-out trace costs:

A 30-day dashboard spanning 1 September mixes both — each trace priced by its own date. That is the point: the total is what you were actually billed, not a re-projection of today’s rate over history.

When the agreement ends, don’t delete the row — close it. PATCH it with "effectiveTo": "2027-01-01" and the window becomes [2026-09-01, 2027-01-01): a trace on 31 December 2026 still uses your rate, a trace on 1 January 2027 falls back to whatever comes next. Your history stays intact.

Cached input

Prompt caching is billed at a different rate from fresh input, so a price row carries a separate cached input rate. Cached tokens are treated as a subset of the input tokens: the cached portion is priced at the cached rate and the remainder at the full input rate. If a row leaves Cached input blank, cached tokens are simply billed at the input rate — a safe over-estimate rather than a silent discount.

The shipped Anthropic rows set cached input at one tenth of the input rate (the cache-read rate) — $0.50/MTok on claude-opus-5, $0.30 on claude-sonnet-5. When you enter your own rate, fill in Cached input if your contract prices it separately; leave it blank if it doesn’t.

Troubleshooting

Related

• Metrics catalogue — the spend_usd, tokens_in, and tokens_out measures and the model slice.
• Model comparison — the other half of the argument: whether the cheaper model still passes your evals, sliced by model and by agent × model.
• Business KPIs — cost_per_case, the same spend divided by the cases it handled (and a floor, not a total, while any model is unpriced).
• Dashboards — build cost widgets, including the Finance cost explorer.
• Traces & sessions — the per-trace Cost column.
• Pre-prod evaluations — the cost gate rule.
• Usage metering — feature-level usage counters, a separate signal from LLM spend.