Recording agent provider decisions preserves the part of an API purchase that ordinary request logs lose. Months after an agent calls a provider, the winning endpoint may still have the request, but it cannot show which alternatives existed or why they were rejected.
That missing context matters when a charge is questioned, a provider starts failing, or an operator wants to know whether an old route still reflects current policy. A durable decision record answers the historical question with the evidence available at selection time. It is not a transcript of an agent's thoughts. It is the compact operational object that connects requirements, candidates, exclusions, and the eventual call.
A provider receipt preserves only the winner
The executed API call creates useful records. A gateway can retain a request identifier, payment status, response status, latency, and retry history. The provider can confirm that its endpoint handled the request. None of those systems saw the complete selection field.
The alternatives disappear unless the routing layer records them. This is the structural reason a provider cannot create its own selection audit trail after the fact. It knows that it won traffic. It does not know whether three candidates failed a price ceiling, whether another candidate was eligible but slower, or whether an operator overruled the original winner.
The same distinction applies to general agent traces. A trace may show that an agent called a comparison tool and then invoked a provider. If it does not retain the compared candidate identifiers, the shared requirements, and the elimination reasons, an investigator still has to reconstruct the decision from changing source data.
Explainable API routing decisions make a choice inspectable at the moment it is returned. Recording turns that one-time response into evidence that remains available after the workflow ends.
Capture the decision boundary as structured fields
A useful record describes the decision boundary, not private model reasoning. It needs enough structure for another system or operator to see what qualified, what failed, and what ranked first.
Record these fields at selection time:
- A stable decision identifier, timestamp, and correlation identifier for the wider workflow.
- The chosen provider and its stable candidate identifier.
- The requirement set, including `max_price`, `max_latency_ms`, `min_reliability`, settlement preference, input requirements, and optimization mode when supplied.
- The rule that selected the winner after hard constraints were applied.
- Every rejected candidate and the exact constraint that removed it.
- Every eligible runner-up in its returned order.
- The comparison weights and each candidate's contribution per measured dimension.
- Every unavailable dimension that was dropped from the weighting.
- References to the executed request, payment, retry, or human override when those events occur.
This is deliberately narrower than a full agent log. Prompt text, retrieved documents, and model messages may have different access and retention rules. The provider decision record can remain queryable without copying sensitive task content into every operational system.
The 0–100 score belongs to one comparison only. It is relative to the candidates in that set, not a permanent provider grade. Preserving the weights and contributions prevents a historical score from being mistaken for a current universal rating.
Keep rejected candidates and runners-up distinct
Rejected candidates and runners-up are both alternatives, but they have different meanings.
A rejected candidate failed a hard requirement. It may have exceeded `max_price`, missed `min_reliability`, failed the latency ceiling, lacked a required input, or conflicted with the requested settlement mode. The record should preserve the exact failed constraint rather than a generic status such as unsuitable.
A runner-up passed the hard requirements and lost during ranking. It remains eligible under the recorded requirement set. That makes it useful for an immediate override or fallback, while a rejected candidate must not be promoted without changing the requirements.
This boundary is why budget-bound API selection starts with the spending limit rather than applying it after ranking. A later reviewer can see that an expensive candidate never qualified, instead of guessing whether price merely reduced its score.
External x402 discoveries require another boundary. Apiosk returns them in a separate `external_candidates` block. They are unreviewed, unmeasured, carry no `candidate_id`, and cannot chain into comparison, decision, or settlement. A discovery lead is not a rejected candidate or an eligible runner-up.
Preserve what was known at that moment
A decision record is a snapshot, not a claim that the winner should remain preferred forever.
Price, measured latency, measured success rate, input compatibility, and payment terms can change. A provider can also be relisted or removed. Re-running today's comparison cannot establish what the router saw months ago. It answers a new question with new evidence.
Preserve the original requirement values and returned candidate order rather than storing pointers that resolve only to current data. If a later policy replaces the old one, add the new policy reference without rewriting the old decision. If an operator chooses a runner-up, record the override and its reason as a subsequent event.
This approach makes changes visible. The history can show that the automated rule selected one provider, a human selected another, and a later run produced a third result after measurements changed. Silent edits collapse those events into one misleading present-tense record.
Connect selection to execution without merging them
Selection and execution should remain separate objects joined by identifiers.
The selection record explains why one provider was chosen. The execution record explains whether the call was sent, paid, retried, completed, or failed. A payment consent record answers a different question again: whether the buyer allowed the spend under its policy. Keeping those boundaries clear makes agent payment consent records usable without pretending that payment approval selected the best provider.
Use the decision identifier on the downstream request where the integration permits it. Carry the same workflow correlation identifier across asynchronous steps. Store only the context required for later reconstruction, redact sensitive values before long-term retention, and keep the record queryable by time, provider, candidate, rule, and outcome.
When execution fails, do not overwrite the selection as if it never happened. Record the failure and whether the workflow used an existing runner-up or ran a fresh decision with updated facts. That distinction separates provider performance from routing policy.
Review records as operational feedback
Individual records answer investigations. Groups of records reveal recurring causes.
A provider can learn whether it repeatedly loses on price, latency, success rate, input compatibility, or settlement requirements. An operator can see whether overrides cluster around a factor the comparison does not measure. Apiosk does not measure result quality or provider terms, so those must never be smuggled into the score as if they were observed dimensions.
Decision history can also expose stale policies. Repeated overrides of the same eligible winner may mean the optimization mode no longer matches the workload. Frequent fresh decisions after execution failures may justify a more explicit paid API fallback route. The records identify the pattern; they do not prove a cause without further review.
Where Apiosk fits
Apiosk separates choosing a provider from recording that choice. `GET /v1/decide?candidates={id},{id}` returns one provider, the rule that picked it, every rejected candidate with the exact constraint that removed it, and the runners-up in order. Requirements passed through discovery and comparison remain attached to the same buying question.
`POST /v1/decisions` is free and unauthenticated. It records which provider was chosen and which alternatives were rejected, so the selection context does not vanish when the provider call begins. The recording step does not turn external discoveries into reviewed candidates, and it does not add measurements Apiosk has not made.
If you operate an endpoint, these records make lost decisions actionable as well as making wins traceable. You can list your API on Apiosk, publish the inputs and terms agents need, and let later review show whether your offer qualified, why it ranked where it did, and what changed before the next decision.
Frequently asked questions
What should an agent provider decision record contain?
It should contain the selected provider, the applied rule and requirements, every rejected candidate with its failed constraint, and the eligible runners-up in order. It should also carry stable identifiers and a timestamp so the record can be connected to the provider call later.
Why is the provider call log not enough?
The winning provider only sees the request it received. Its log cannot show which competitors were considered, which constraints removed them, or which eligible provider ranked second.
Should a decision record include an agent's hidden reasoning?
No. The useful evidence is the observable requirement set, candidate set, applied rule, measurements, exclusions, and resulting order. Those fields can be inspected without storing private chain-of-thought.
When should an agent provider decision be recorded?
Record it when the provider is selected, before candidate data or measurements can change. Link the resulting decision identifier to the executed API request, payment record, retry, and any later override.