Choosing a model

Every model on the marketplace is served by one or more endpoints, each with its own price and its own measured behaviour. Choosing well means reading two kinds of numbers — the prices a provider declares and the performance Heimdallm measures — and knowing which knobs steer your traffic between endpoints. This tour uses the model page, then the API equivalents.

Browsing the catalogue#

The models page groups every live model by family. Each model summary selects a live endpoint by prompt-token price, then completion-token price, with unknown prices last. For media this is a representative endpoint, not a lowest-price guarantee. Expand a row to compare versions, then compare their endpoints in the same billing unit. From a model page you get the full picture — and GET /models / GET /models/:author/:slug/endpoints give you the same fields programmatically for building your own comparison views (see the catalogue reference).

Start from what excludes, then rank what remains:

• Modality — text in/text out, or image input (input_modalities), audio input for transcription, embeddings output. A model that cannot do the job is not cheap.
• Context length — per endpoint, not per model. The same weights can be served with different windows; the endpoints listing carries each one.
• Parameters — if you need tools, response_format, or seed, check supported_parameters per endpoint. Routing considers only endpoints that declare every optional setting you explicitly send. reasoning_effort is matched per level: a known domain excludes values it does not declare, and a failed check withholds the current declared value it refutes. Check each endpoint's reasoning metadata for its effort choices and defaults. Missing choices mean the domain is unknown, not that every level works. Thinking on/off, graded effort and a token budget are separate controls; their forwarding depends on the adapter. See reasoning routing.
• Policies — zdr, hipaa, data-training and retention declarations, all per endpoint. A ZDR declaration additionally requires its provider to pass marketplace review before zdr: true routes to it. See Data & privacy.

The Discount filter keeps the models whose quoted endpoint charges less than the price it publishes, and the Biggest discount sort orders what remains by the fraction taken off, largest first. Every price in the list is already net of that fraction, so a discounted row is one whose badge names the published figure its prices came off; a model whose endpoints all charge what they publish carries no badge and never reaches the filtered list.

Reading prices#

Prices are per token, published as exact decimals, and the listed price is the billed price — there is no markup. A few habits keep them honest:

• Compare per million tokens. "0.0000004" is $0.40 per million. Model pages show prices per million (and per audio hour, per megapixel, per request where those units apply).
• Prompt and completion differ — often by a lot. Compute the cost of your mix: for a workload of 2 000 prompt tokens and 500 completion tokens at $0.10 / $0.40 per million, the prompt side costs $0.0002 and the completion side $0.0002 — not the workload you would guess from either number alone.
• Cache pricing is a real lever. An endpoint that declares cached_prompt bills cache-read tokens at that lower rate, reported in usage.prompt_tokens_details.cached_tokens. If your prompts repeat — system prompts, retrieved context, few-shot blocks — a cache-capable endpoint can be dramatically cheaper than its headline price.
• Price history is public. Model pages chart each provider's price over time as step lines. A provider that holds its price and one that ratchets it read differently at a glance.
• Free endpoints exist. An endpoint whose document declares it free is billed at zero for every unit that document prices, and :free routes only to endpoints carrying that declaration — an endpoint that merely publishes zeros is billed at them and the suffix passes it by. A price of zero on a transcription's token side means nothing either way; transcription is billed per second of audio.

Reading measurements#

Measured figures come from real traffic and periodic probes, per endpoint, and each carries its window — 30 minutes, one day, or (for tool calls) two hours. A figure stays null until its window holds enough samples; absence means "not yet earned", never "zero" or "bad".

Percentiles, not averages. p50 is the typical request; p90 and p99 are the tail. A p50 of 0.4 s with a p99 of 4 s is a different product than 0.8 s flat — pick by which one your users feel. For interactive use, TTFT dominates perception; for batch work, throughput and response time dominate wall-clock.

Hourly history. The performance section charts TTFT and throughput by hour over the last week, and the uptime section shows availability by hour. One flat line and one with a daily sag at peak hours are different endpoints to build on, whatever the point estimates say.

Benchmarks are per endpoint. The same weights at a different quantization, or served with different settings, score differently — so scores attach to endpoints, not models. Grading uses the declared automatic evaluator, and each score carries its sample count. Use benchmarks to compare endpoints of one model; use your own evaluation for the choice between models.

Steering between endpoints#

Once a model has your trust, the endpoints still differ by the minute. Three layers of control, in order of precedence — request fields, then the model id's suffix, then workspace defaults:

• Suffixes — :floor (cheapest first), :nitro (fastest first), :free (endpoints declared free only). Quick, per-request, self-documenting.
• The provider object — pin with order or only, exclude with ignore, cap with max_price, require declarations with zdr / data_collection, insist on parameters with require_parameters, or sort by price, throughput or latency. The full field table is in Models & routing.
• Fallbacks — models lets a cheaper first choice fail over to a sturdier backup, in order. For anything in production, this is the difference between an incident and a log line.

A practical pattern for cost-sensitive work: primary model with :floor, a pinned quality backup in models, and a workspace max_price so a price change elsewhere can never route an unbounded price to you.

When the choice changes under you#

Endpoints come and go as providers operate. A 503 with metadata.rejections tells you exactly which constraint eliminated which endpoint; a withdrawn endpoint is gone from the catalogue with its history kept; a price change is a step in the price history. If your integration re-checks the endpoints listing (or the status board) on a schedule, it will see these moves before your users do.

Compare benchmark evidence#

The benchmark explorer compares named benchmark results for currently served provider and quantization variants. Scores appear after five scored questions and show the exact dataset count and percentage tested. Provisional samples are distinct from complete runs, and both carry protocol identity and measurement dates. A missing metric is not zero.

GET /api/v1/benchmarks publishes the overview. GET /api/v1/benchmarks/variants/{endpointId} provides bounded task evidence. Comparisons require the same benchmark and protocol; provisional provider averages also require the same tested questions. Task-cost estimates use measured usage at current public prices where every required pricing input is known.