DocsConcepts

Offering status

How offerings are charged, why some are hidden, and what happens as a provider deprecates, redirects or retires a model.

An offering with the right capabilities can still be left out of answers, because of how it is charged, who makes it, or where it is in its life. All of this is on the offering in /v1/models, and no_candidate counts what each of these removed.

How it is charged

billing_status states how an offering is charged, because in the sources a price of 0 or no price at all can mean any of these. An unknown price is never read as free.

`billing_status`	Meaning	As an answer
`metered`	A published price; `billing_units` says what it charges by, such as `token` or `image`.	Yes
`free`	Offered at no charge; `free_since` says how long the claim has stood.	Yes
`trial`, `included`	An evaluation with no production price, or part of a plan.	Only with `allow_trial=true`, with a `trial_offering` warning.
`variable`	The price depends on the route a request takes.	No
`unknown`	No published price the catalog could read.	No

Budget bands count only metered and free offerings. max_price needs a price, so a trial with no price never passes it.

Hidden offerings

hidden gives the reason an offering is listed but never chosen: unreviewed_vendor (a maker we haven't reviewed), router (a router that picks its model per request) or stealth (an undisclosed maker). No request can turn one into an answer.

Hidden offerings leave the default /v1/models list, and include_hidden=true brings them back. Looking a model up by id always works. The sandbox and the model directory leave them out.

When an offering ends

Only ga offerings are answers, plus preview ones with allow_preview=true. A deprecated offering still works and is still listed, but is no longer recommended.

deprecated_on: the day the provider's deprecation takes effect.
retires_on: the provider's end date. Past it the offering is retired.
end_claimed_on: an end a catalog claims and the provider hasn't confirmed. Passing it retires nothing: the offering stays deprecated until the provider's own page, its complete model list or a probe says it has gone.
retires_not_before: the provider's floor. A claimed end before it is ignored.
redirect: the provider answers this id with another model and bills it as that model (to), from on or already if there is no on. A redirect is not a retirement, since the id keeps answering. via marks a route whose upstream redirects, which the router itself hasn't announced.

Answers warn ahead of time: see warnings.