How it works

This page explains the concepts behind Model Router — read it once and every other page will make more sense.

The prepaid balance

Your facility holds a prepaid balance in USD. It only moves in two directions:

• Up when you top up (manually, via auto top-up, or by an adjustment credited to your account). Top-ups appear instantly.
• Down as usage accrues. Usage is reported live by the inference service and reconciled against your prepaid balance every 15 minutes, so very recent activity can take a few minutes to appear in Monthly usage. The transaction history lists top-ups and balance adjustments only.

The balance is the financial wall: when it reaches zero, inference requests are blocked with an insufficient credits error until you top up. Listing models still works with a zero balance, so integrations can discover the catalog before you fund the account.

The model catalog

The catalog contains models from many providers, each priced per million tokens (input and output priced separately, shown in the Models settings). All models are enabled by default for your facility; you can:

• Disable models account-wide in Settings → Models (at least one model must stay enabled).
• Restrict models per API key or per connected service — a tighter list on top of the facility's enabled set.

A special catalog entry, auto (the Auto Router), has no price of its own. For each request it automatically selects the best model based on the prompt's complexity, and you're billed at the rate of the model it picks. See Models.

Two ways to consume models

1. Connected Services

AI Agent devices paired with your facility connect to Model Router automatically — no API key is ever entered on the device — and Workflows can connect as well. Each connected service appears in Settings → Service Access & API Keys under Connected Services with its own spend figures, and you can give each one its own spend limits, model restrictions, and guardrail overrides. See Connected Services.

2. Your own API keys

You can provision API keys (they start with phk_) so third-party software and systems that support BYOK (Bring Your Own Key) can connect to models published by Performance Hub. The endpoint is OpenAI-compatible — point any OpenAI SDK or tool at the base URL and authenticate with your key. See API keys and Connecting your application.

Both paths draw from the same balance, respect the same account-wide spend limits, appear in the same Activity analytics and Logs, and can be individually bounded.

Balance vs spend limits

These are two different mechanisms, and both apply:

Account spend limits come in three windows — daily (resets every day at midnight, facility local time), monthly (resets on the 1st of each month, facility local time), and a lifetime hard cap (counts spend since the last manual reset; never resets on its own). Any combination can be active at once, and limits apply across every API key and connected service combined. The prepaid balance still applies on top.

Per-key and per-service limits work the same way (daily, monthly, lifetime) but count only that key's or service's spend. When a limit is hit, only that key or service is blocked — the rest of the facility keeps working.

How a request is processed

When a request arrives at the endpoint, checks run in this order:

1. Authentication — a valid API key or connected-service identity. For an API key, a facility where Model Router isn't enabled is rejected here with HTTP 403 ("Model Router is not enabled for this facility"). Listing models (GET /v1/models) is answered straight after authentication, so it keeps working at a zero balance.
2. Prepaid credit check — available balance must be above $0 (for connected services, Model Router must also be enabled); otherwise the request is rejected with an insufficient credits error (HTTP 402).
3. Account spend limits — if a daily, monthly, or lifetime cap is breached, the request is rejected with a budget exceeded error (HTTP 402) that states when the window resets, in your facility's timezone.
4. Per-key / per-service spend limits — same check, scoped to the calling key or service.
5. Prompt checks — the prompt-injection shield and your custom content filters run on the prompt. A block filter or an injection hit rejects the request (HTTP 403, content policy violation); redact filters rewrite matches to [REDACTED] and let the request continue.
6. Model routing — auto is resolved to a concrete model by the Auto Router (a request containing an image is sent to a vision-capable model you allow). Fallback models are filtered to the ones the key may use, your reasoning setting is applied when the request does not set its own, and requested output limits are clamped to what the model supports.
7. Inference — PII masking and secret redaction (when enabled) are applied by the inference service before the prompt reaches the model; the request then goes to the model provider and the response streams back.

Rate limits (requests/min and tokens/min, if set on the key or service) are enforced throughout; exceeding them returns HTTP 429.

What is recorded

Every request is logged with its metadata: time, model (both the requested model and the one the router resolved), provider, tokens (prompt, completion, cached, reasoning), cost, latency, time to first token, speed, status, and the calling key or service. Prompt and response content is never stored.

Usage and spend figures shown in the module are the same figures used for enforcement, so what you see as "limit reached" is exactly what gets blocked.

Glossary