Estimate

Request

A JSON body with a model and the usage you want priced. Everything else has a default. The schema is strict: an unrecognized key is a 400, not a silently ignored field — a typo in a usage field would otherwise quietly under-bill.

curl -X POST localhost:8080/v1/estimate -H 'content-type: application/json' -d '{
  "model": "claude-sonnet-4-5",
  "usage": {
    "input_tokens": 190000,
    "output_tokens": 4000,
    "cache_read_tokens": 20000,
    "cache_creation_tokens_by_ttl": { "1h": 8000 }
  }
}'

Every numeric usage value must be finite and >= 0. The body limit is 256 kB.

Usage fields

Each field maps to one base rate key. If the model does not declare that key — or a variant of it that fits the tier and TTL — the quantity lands in unpriced[], never in the total at a made-up rate.

Text tokens

Audio, image and video

Non-token units

Examples across modalities

# Embeddings: input only — 2.5M tokens of text-embedding-3-small
{ "model": "text-embedding-3-small", "usage": { "input_tokens": 2500000 } }
# -> 0.05 USD  [input.text 2500000 x 2e-8]

# Transcription priced per second of audio
{ "model": "assemblyai/best", "usage": { "audio_seconds": 3600 } }
# -> 0.119988 USD  [input.audio_seconds 3600 x 0.00003333, plus output.audio_seconds at 0]

# Image generation, priced per image
{ "model": "dall-e-3", "usage": { "input_images": 4 } }
# -> 0.16 USD  [input.images 4 x 0.04]  + DEPRECATED_MODEL warning

# OCR, priced per page
{ "model": "azure_ai/mistral-document-ai-2505", "usage": { "pages": 320 } }
# -> 0.96 USD  [other.pages 320 x 0.003, rate_key ocr_cost_per_page]

Service tiers

batch, priority and flex select a rate variant — input_cost_per_token_batches, ..._priority, ..._flex. OpenAI's batch tier is the familiar case: half price.

{ "model": "gpt-4o", "usage": { "input_tokens": 500000, "output_tokens": 50000 }, "service_tier": "batch" }

input.text   500000 x 0.00000125 = 0.625  [input_cost_per_token_batches]
output.text   50000 x 0.000005   = 0.25   [output_cost_per_token_batches]
                                   -----
                                    0.875 USD

When the model has no rate for the tier you asked for, the estimator degrades to standard and says so — it does not fail, and it does not pretend the discount applied. Compare service_tier_requested with service_tier_applied in resolution, or look for SERVICE_TIER_NOT_PRICED in the warnings:

{ "model": "gpt-4o", "usage": { "input_tokens": 1000, "output_tokens": 100 }, "service_tier": "flex" }

"resolution": { "service_tier_requested": "flex", "service_tier_applied": "standard", … }
"warnings": [
  { "code": "SERVICE_TIER_NOT_PRICED",
    "message": "The model has no \"flex\" rate for input_cost_per_token; falling back to standard.",
    "field": "input_tokens" }, … ]

Context tiers

Several providers charge more once a prompt crosses a threshold — Anthropic and Google at 200k tokens, for instance. The catalog encodes it as parallel keys: input_cost_per_token_above_200k_tokens.

Which tokens count toward the threshold is options.threshold_basis. By default cache reads count too (input_plus_cache), because the provider still has to hold that context — that is why the example below reports 218,000 considered tokens for 190,000 input tokens.

{ "model": "claude-sonnet-4-5",
  "usage": { "input_tokens": 190000, "output_tokens": 4000,
             "cache_read_tokens": 20000, "cache_creation_tokens_by_ttl": { "1h": 8000 } } }

"resolution": {
  "threshold_basis": "input_plus_cache",
  "threshold_tokens_considered": 218000,
  "context_tier_applied": "above_200k_tokens",
  "context_tier_thresholds_available": [200000]
}

Set threshold_basis: "input_only" to leave cache out of the comparison.

Cache and TTL

Cache writes are priced by how long the entry lives. _above_1hr is not a volume threshold — it is Anthropic's 1 hour TTL, and it composes with the context tier, which is how a single line ends up billed with a quadruple key:

cache_write.1h  8000 x 0.000012 = 0.096  [cache_creation_input_token_cost_above_1hr_above_200k_tokens]

cache_creation_tokens and cache_creation_tokens_by_ttl["5m"] are added together into one 5-minute line; the "1h" bucket always gets its own.

If the model declares prompt_cache_min_tokens and your cache write is below it, the write is still billed — but you get a CACHE_BELOW_MIN_TOKENS warning saying the provider would not have cached it at all.

If your provider reports cache reads inside input_tokens rather than alongside them, set options.cache_tokens_included_in_input: true and the overlap is subtracted instead of billed twice.

Regional uplift

18 models declare regional_processing_uplift_multiplier_eu / _us. Setting region_processing applies it as a separate surcharge line over the USD subtotal, rather than by multiplying each rate — so the base rates in the breakdown stay comparable to the catalog.

{ "model": "gpt-5.6", "usage": { "input_tokens": 10000, "output_tokens": 1000 }, "region_processing": "eu" }

input.text            10000 token x 0.000004 = 0.04   [input_cost_per_token]
output.text            1000 token x 0.00002  = 0.02   [output_cost_per_token]
surcharge.region_eu       1 request x 0.1    = 0.006  [regional_processing_uplift_multiplier_eu]
                                               -----
                                                0.066 USD

A model with no uplift key is unaffected — no line, no warning, same total as global.

Options

Response shape

{
  "model": { "requested": "claude-sonnet-4-5", "resolved_key": "claude-sonnet-4-5",
              "provider": "anthropic", "mode": "chat" },
  "dataset": { "sha256": "a5682d2f…", "loaded_at": "2026-08-27T06:23:42.602Z" },
  "totals": { "USD": { "exact": "1.338", "rounded": "1.3380000000", "decimals": 10 } },
  "lines": [ … ],
  "subtotals": { "input": "1.14", "output": "0.09", "cache_read": "0.012", "cache_write": "0.096" },
  "resolution": { … },
  "warnings": [ … ],
  "unpriced": [ … ]
}

dataset.sha256 is the digest of the snapshot that produced this answer — pin it if you need two estimates to be comparable. Every monetary value is a string, because these are exact decimals and JSON numbers are not.

Totals

totals is keyed by currency, not a single number, because the catalog carries rates in Databricks DBU alongside USD. exact is the unrounded decimal; rounded honours round_to.

subtotals groups the lines by category: input, output, cache_read, cache_write, surcharge, other.

Cost lines

{
  "id": "cache_write.1h",
  "label": "Cache write",
  "category": "cache_write",
  "currency": "USD",
  "quantity": 8000,
  "unit": "token",
  "rate": "0.000012",
  "rate_key": "cache_creation_input_token_cost_above_1hr_above_200k_tokens",
  "rate_per_units": 1,
  "amount": "0.096",
  "notes": ["Cache write with a 1 hour TTL.", "Long-context rate: 218000 > 200000 tokens (flag tier)."]
}

Resolution

Every judgement call, in one object — this is what you inspect when a total surprises you.

"resolution": {
  "service_tier_requested": "standard",
  "service_tier_applied": "standard",
  "tier_policy": "flag",
  "threshold_basis": "input_plus_cache",
  "threshold_tokens_considered": 218000,
  "context_tier_applied": "above_200k_tokens",
  "context_tier_thresholds_available": [200000],
  "pricing_mechanism": "flat_keys",
  "rate_keys_used": [
    "input_cost_per_token_above_200k_tokens",
    "output_cost_per_token_above_200k_tokens",
    "cache_read_input_token_cost_above_200k_tokens",
    "cache_creation_input_token_cost_above_1hr_above_200k_tokens"
  ]
}

context_tier_applied is null when no threshold was crossed, and context_tier_thresholds_available tells you whether the model has any thresholds at all. pricing_mechanism is always "flat_keys" today — tiered_pricing is not read.

Warnings

Warnings never change the status code. They are how the estimator tells you it made a decision you might disagree with, or that the number is right but the request is not.

# wandb/zai-org/GLM-4.5 at $55,000/MTok — served as-is, flagged loudly
"warnings": [
  { "code": "SUSPICIOUS_RATE_MAGNITUDE",
    "message": "Rate input_cost_per_token=0.055 implies $55000/MTok. Likely an upstream dataset error." } ]

o1-pro at $600/MTok is genuinely that expensive and sits in an allowlist, so it produces no warning.

Unpriced usage

The rule that shapes this endpoint: a missing rate is never billed as 0. 258 models legitimately declare output_cost_per_token: 0, so "free" and "unknown" have to stay distinguishable. Usage the catalog cannot price is listed here, with the keys that were tried.

{ "model": "dashscope/qwen-flash", "usage": { "input_tokens": 1000, "output_tokens": 100 } }

"totals": { "USD": { "exact": "0", … } },
"lines": [],
"unpriced": [
  { "usage_field": "input_tokens",  "quantity": 1000, "reason": "NO_RATE_KEY", "candidate_keys_checked": ["input_cost_per_token"] },
  { "usage_field": "output_tokens", "quantity": 100,  "reason": "NO_RATE_KEY", "candidate_keys_checked": ["output_cost_per_token"] }
]

reason is one of NO_RATE_KEY, MODE_MISMATCH or NON_MONETARY_UNIT; in practice only the first is emitted.

Errors

# A typo in a usage field is a 400, not a silent zero — the schema is strict
{ "model": "gpt-4o", "usage": { "input_tokens": 1000, "input_toknes": 500 } }

{ "type": "about:blank#invalid-request", "title": "The request is not valid.", "status": 400,
  "errors": [{ "path": "usage", "message": "Unrecognized key(s) in object: 'input_toknes'" }] }

# limit_policy: "error" turns the limit warning into a refusal
{ "type": "about:blank#limits-exceeded", "title": "The limits declared by the model are exceeded.",
  "status": 422, "detail": "5000000 input tokens exceed max_input_tokens=128000.",
  "max_input_tokens": 128000, "provided": 5000000 }

# The model exists, but the catalog publishes no rate for it
{ "type": "about:blank#model-not-priced", "title": "The model exists but carries no pricing data.",
  "status": 422, "detail": "The dataset publishes no rate for this entry.",
  "model": { "id": "github_copilot/claude-opus-4.5", "provider": "github_copilot", "mode": "chat" } }

What the estimator cannot price

These are accepted inputs or catalog features that currently produce no cost line. They are written down rather than hidden, because a silently missing charge is worse than a documented one.

If one of these blocks you, the issue tracker is the place to say so.