beacon pricing

​

Command overview

beacon pricing show <model> [--json]
beacon pricing list [--provider <name>] [--json]
beacon pricing info [--json]
beacon pricing validate [--json]

​

Where prices come from

1. Your overrides file, if there is one. It can price models the catalog cannot know (internal or proprietary models, releases newer than your Beacon build, names a gateway invents) and replace list prices with the rates your organisation actually pays.
2. The catalog embedded in Beacon: the providers’ published standard-tier API list prices, generated from LiteLLM’s model price list. beacon pricing info prints its source, upstream commit and generation date.

​

The overrides file

{
  "schema": "beacon.pricing.overrides/v1",
  "comment": "Acme enterprise agreement, effective 2026-07-01",
  "models": {
    "claude-sonnet-4-5": {
      "provider": "anthropic",
      "comment": "20% off list",
      "input_usd_per_mtok": 2.4,
      "output_usd_per_mtok": 12,
      "cache_read_usd_per_mtok": 0.24,
      "cache_write_usd_per_mtok": 3,
      "cache_write_1h_usd_per_mtok": 4.8,
      "bands": [
        { "above_tokens": 200000, "input_usd_per_mtok": 4.8, "output_usd_per_mtok": 18,
          "cache_read_usd_per_mtok": 0.48, "cache_write_usd_per_mtok": 6,
          "cache_write_1h_usd_per_mtok": 9.6 }
      ]
    },
    "acme-coder-2": {
      "provider": "acme",
      "input_usd_per_mtok": 1,
      "output_usd_per_mtok": 4
    }
  },
  "aliases": {
    "my-gateway-model": "claude-sonnet-4-5",
    "router/fast": "gpt-5-mini"
  }
}

​

Rules

• Rates are US dollars per million tokens, written as JSON numbers: 3, 0.3, 2.5e-1. Beacon converts each one exactly to integer microdollars, so 0.3 is exactly 300,000 microdollars per million tokens. A value finer than one microdollar per million tokens (more than six decimal places) is refused rather than rounded.
• Refused values, each with an error naming the key: negative numbers, 0 (leave a field out when a rate is unpublished; a zero would make tokens free), quoted numbers such as "3.00", anything above $100,000 per million tokens (almost always a per-token or per-thousand price in the wrong field), unknown fields (usually a misspelled rate), and a key written twice.
• A row replaces the catalog row whole. Fields you leave out are unpublished, not inherited from the catalog, and are priced the way the catalog prices a missing rate: cache reads and cache writes at the row’s input rate, one-hour writes at its five-minute write rate. Those fallbacks are named in the report’s pricing.models[].fallbacks and by beacon pricing show.
• Bands apply to every token of a single request whose prompt (input plus cache read plus cache write) is above above_tokens, exactly as the catalog’s bands do, and only to usage Beacon knows is one request (see How the estimate is computed). A band needs to state only what changes; every rate it leaves out is the row’s base rate. Bands may be listed in any order; two bands at the same threshold are refused.
• Matching. A row or alias name is matched with the same ladder as the catalog: the exact reported name first, then case and provider prefix (anthropic/Claude-Sonnet-4-5), dotted versions (claude-sonnet-4.5), Bedrock route prefixes, and after stripping a [1m] marker, a snapshot date or an effort suffix. So a row for claude-sonnet-4-5 also prices claude-sonnet-4-5-20250929, even though the catalog has a row for that exact snapshot.
• Overrides win. When any name in the file matches a model, the file decides; the catalog is consulted only for models no override name reaches. If two names in the file match a model at the same rung with different prices, the model is left unpriced rather than priced at a list price the file was written to replace; beacon pricing validate warns about such names.
• Aliases point at an exact name: a row in this file (checked first) or a catalog key from beacon pricing list. An alias cannot also be a row, and a target that exists in neither list is refused.

​

Auditing an estimate

"pricing": {
  "catalog": { "name": "LiteLLM model_prices_and_context_window.json", "commit": "1238cfe9...", "generated_at": "2026-10-05" },
  "overrides": {
    "path": "/Users/alice/.beacon/endpoint/pricing/overrides.json",
    "sha256": "db4de2c8d714...",
    "models": 2,
    "aliases": 2
  },
  "models": [
    { "model": "acme-coder-2", "key": "acme-coder-2", "source": "override", "match": "exact", "...": "..." },
    { "model": "my-gateway-model", "key": "claude-sonnet-4-5", "source": "override", "alias": "my-gateway-model", "...": "..." }
  ]
}

​

beacon pricing show

beacon pricing show 'claude-sonnet-4-5-20250929[1m]'

Model:      claude-sonnet-4-5-20250929[1m]
Priced by:  catalog key "claude-sonnet-4-5-20250929"
Provider:   anthropic
Match:      exact after stripping context_window
Rates (USD per million tokens):
  input             3.00
  output            15.00
  cache read        0.30
  cache write (5m)  3.75
  cache write (1h)  6.00
Long-context bands (a single request whose prompt is above the threshold is billed at the band's rates for every token):
  above 200000: input 6.00, output 22.50, cache read 0.60, cache write 7.50, cache write 1h 12.00

​

beacon pricing list

​

beacon pricing info

​

beacon pricing validate

beacon pricing validate --pricing-file ./overrides.json

ok: ./overrides.json (sha256 db4de2c8d714): 2 model(s), 2 alias(es)
  model  acme-coder-2
         unpublished, priced by fallback: cache_read_at_input_rate, cache_write_at_input_rate, cache_write_1h_at_write_rate
  model  claude-sonnet-4-5 replaces the catalog entry of the same name
  alias  my-gateway-model -> claude-sonnet-4-5 (override)
  alias  router/fast -> gpt-5-mini (catalog)