Field note 01Published Aug 31, 2026

What an API key can actually tell you

A key is not a tiny account database. It is an opaque credential that lets a provider look up an account, apply policy, and return a small, provider-specific slice of that account's state.

Identity

Does the credential authenticate, and what can it access?

Entitlement

Which models, tiers and free allowances apply?

Meter

What has been used, and what limit remains?

Capacity

Can the service accept work right now?

The request-to-status flow

user gives key
      ↓
provider adapter selects the right base URL and auth format
      ↓
safe metadata request: /key, /models, or a provider health endpoint
      ↓
HTTP status + response headers + JSON body
      ↓
normalize into: valid · tier · models · usage · limits · reset · unknowns
      ↓
display provider-reported facts separately from observed capacity

The adapter is the important part. There is no universal API for “balance” or “remaining capacity”; each provider chooses its own endpoint, header names, scopes and refresh behavior.

What the major providers expose

Provider	Useful response headers	Account APIs / surfaces	Key can reveal	Still unknown
OpenRouter	X-Generation-Id; optional cache and router metadata	GET /api/v1/key; /api/v1/credits; management analytics	Free-tier flag, key usage, configured limit, remaining limit, expiry and BYOK usage	Live provider capacity
OpenAI	x-request-id; x-ratelimit-*; openai-organization; openai-processing-ms	Organization Usage and Costs APIs	Accessible models and per-response request/token limits	Billing history from an ordinary inference key
Anthropic	anthropic-ratelimit-*; retry-after; workspace ID where available	Rate Limits API and Admin usage reports	Request, total-token and input-token limits and remaining amounts	Guaranteed minimum serving capacity
Google Gemini	No universal remaining-quota header is documented	Google AI Studio and Cloud quota/billing surfaces	Project-scoped model access and response usage metadata	Exact quota and live capacity from the key alone
Groq	x-ratelimit-*; retry-after; 498 for Flex capacity exhaustion	Console Limits, Projects, Billing and metrics	Remaining request and token limits in inference responses	Organization billing without account permissions
Mistral	X-RateLimit-Remaining; 429 on request/token limit exhaustion	Admin rate-limit and spend-limit APIs	Observed remaining limit and response usage where returned	Full organization limits from a normal key
Fireworks	X-Ratelimit-Limit-Tokens-Prompt; fireworks-* token headers	Account and project console	Prompt and cached-prompt token counts plus prompt-token limit	A complete monetary balance in the inference response
Together AI	No universal remaining-limit header prominently documented	Project and organization usage/cost analytics	Project scope, accessible models and response usage	Per-key spend or rate cap; limits are organization-level
OpenCode Zen	Structured status and usage responses; no stable public quota-header contract	Zen console, credits, auto-reload and workspace/member limits	Gateway model access and request usage	Live shared capacity or upstream provider identity unless exposed by the route
DeepSeek	HTTP status and usage; balance/concurrency failures are primarily error-body signals	Account billing and usage console	Model access, request success and token usage	A documented live-balance endpoint or stable limit-header scheme
NVIDIA NIM	Deployment-specific; health and metrics endpoints are more important than quota headers	NVIDIA cloud account or local deployment configuration	If self-hosted: liveness, readiness, metadata and Prometheus metrics	One quota policy covering hosted and self-hosted NIM
ElevenLabs	character-cost, request-id and x-trace-id	Subscription character allowance, reset and concurrency settings	Audio generation cost in characters and request correlation	USD cost without applying the account’s authoritative plan rate
Deepgram	Request IDs and typed service/model/region concurrency errors	Project usage, billing and concurrency configuration	Audio request success, model/service and usage where returned	Token-style limits; audio is usually measured in duration and concurrency
Cartesia / Fish Audio	Provider-specific request IDs and structured concurrency or wallet errors	Console wallet, package allowance or concurrency settings	Audio request outcome and provider usage units	That credits or characters represent USD without a plan-specific conversion

Provider-reported

Limits and balances

Use an endpoint or header when the provider supplies one. Attach a timestamp and scope: key, project, workspace or organization.

Observed

A successful request

Record model, provider, latency, status, usage and generation ID. This describes what just happened, not a reservation.

Unknown

Live capacity

A 200 proves one request worked. It does not reveal how much shared GPU capacity remains five seconds later.

Implementation rule

Never label a model “free” only because its catalog price is zero. Check account entitlement, quota, reset policy and billing scope. Never label a provider “available” only because its model list contains the model.

Primary references: OpenRouter ↗, OpenAI ↗, Anthropic ↗, Gemini ↗, Groq ↗, Mistral ↗, OpenCode Zen ↗, NVIDIA NIM ↗, ElevenLabs ↗.