Usage that tells the truth
A gateway call can return HTTP 200 with nothing in it. Your usage page should say so. Four outcome states that sum to your total, real calendar ranges, and a key recommendation that is allowed to say no.
Four outcomes, not a status code
A success rate built from HTTP status cannot tell a working alias from a dead one. Every chat turn now lands in exactly one of four states, and the four sum to your total. Requests we cannot classify read unknown, and they are never folded into delivered.
delivered
Something came back that you can use.
hollow
The call succeeded and returned nothing at all.
failed
The call errored.
unknown
We cannot tell. Shown as unknown, never as a confident zero.
// the four states are mutually exclusive and sum to total
outcome: {
delivered: 640, hollow: 118,
failed: 41, unknown: 13,
total: 812,
measurable_from: "2026-08-13" // read it, do not hard-code it
}A key recommendation allowed to say no
The easy version of a capacity panel always says buy more. Each provider here gets a verdict in words, and four of the six refuse. Where errors are not rate limits, or the cap sits on the account rather than the key, the panel says more keys will not help and suggests none at all.
add_keys
The only verdict that carries a number, and it is the recommended total.
not_quota
Errors are high but they are not rate limits. Keys will not fix it.
account_capped
The ceiling is on the account. One more key is refused identically.
unmeasurable
We cannot tell, and you should not infer either way.
// a verdict that cannot say no is not a recommendation
provider: "mistral",
verdict: "not_quota",
suggested_keys: null,
limit_source: "estimated_from_429" // an estimate, and it says soThe same numbers your agent reads
Ask for a calendar month rather than a rolling lookback, put the previous period beside it, and read back the range the server resolved. Your agent gets the identical payload over the identical window, so it can ask what you would ask and act on the answer.
# THIS MONTH is a calendar range. A lookback cannot express one.
curl -s "https://spideriq.ai/api/v1/brands/$BRAND_ID/gate/usage?from=2026-08-01T00:00:00Z&to=2026-09-01T00:00:00Z&compare=true" \
-H "Authorization: Bearer $SPIDERIQ_PAT"gate_usage
Spend, volume and the outcome split over any window.
gate_capacity
Key pressure and subscription windows, with the verdicts.
gate_flow
What you asked for against what actually served it.