Function: probeProviderKey()
probeProviderKey(
options):Promise<ProbeProviderKeyResult>
Defined in: packages/agentos/src/api/probeProviderKey.ts:170
Probes one API key with its provider's billing probe, the smallest billable request, and says what the answer
shows: ok, exhausted (no credit, or a spend limit reached), invalid (a bad, revoked or expired key),
throttled (a rate limit) or unknown (any other answer, or none). The answer is read by
classifyKeyFailure(), as a request's is in the key pool. A probe costs one request of one or a few output
tokens on a passing key.
No key is read from the environment and no pool takes part: the probe sends the key it is given to the provider's
own endpoint, or to baseUrl. The one variable that changes what it sends is AGENTOS_OPERATION_ID_HEADER: on
Anthropic, OpenAI and OpenRouter it names the header each of the probe's requests carries an operation id in. It
never throws for an answer; it throws before any request for a provider it has no probe for (RangeError), a
missing key or a comma-separated list (TypeError), a timeoutMs that is not a positive finite number
(RangeError), and an AGENTOS_OPERATION_ID_HEADER those three providers refuse as a header name (RangeError).
Parameters
options
The provider, the key, and optionally the model, the base URL, the timeout and an abort signal.
Returns
Promise<ProbeProviderKeyResult>
The state, a detail line without the key, the key's fingerprint, and the status, model and Retry-After when the answer had them.
Example
const keys = process.env.ANTHROPIC_API_KEY!.split(',').map((key) => key.trim()).filter(Boolean);
const states = await Promise.all(keys.map((apiKey) => probeProviderKey({ provider: 'anthropic', apiKey })));
// [{ state: 'exhausted', detail: 'no credit or a spend limit reached (HTTP 400): Your credit balance is too low ...', ... },
// { state: 'ok', detail: 'key accepted: HTTP 200 on claude-haiku-4-5-20251001', ... }]