How it works

This page explains the concepts behind AI Models, Credits & Usage — 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 charges accrue. Usage is reported live by the inference service and reconciled every 15 minutes against your ledger, so very recent activity can take a few minutes to appear in the transaction history.

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 agent — 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 AI Agents

AI Agent devices paired with your facility connect to AI Models automatically — no API key is ever entered on the device. Each agent appears in Settings → Agent Access & API Keys with its own spend figures, and you can give each one its own spend limits, model restrictions, and guardrail overrides. See AI Agents.

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 agent combined. The prepaid balance still applies on top.

Per-key and per-agent limits work the same way (daily, monthly, lifetime) but count only that key's or agent's spend. When a limit is hit, only that key or agent 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-agent identity.
2. Prepaid credit check — the facility must be enabled with available balance above $0; 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-agent spend limits — same check, scoped to the calling key or agent.
5. Guardrails and content filters — PII masking, secret redaction, prompt-injection shielding, 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; requested output limits are clamped to what the model actually supports.
7. Inference — the request is forwarded to the model provider and the response streams back.

Rate limits (requests/min and tokens/min, if set on the key or agent) 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 agent. 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