Catalog
Access tiers
Every model sits in one of three tiers. The tier decides who may call it, independently of price.
| Field | Type | Description |
|---|---|---|
free | any account | Callable on every plan, including the free one, within a daily token allowance. |
paid | plan or balance | Needs an active paid plan or a positive wallet balance. Trial credit counts. |
premium | paying accounts | Flagship models. Unlocked once the account has made a real payment — gifts, referrals and trials do not unlock this tier. |
Why premium is separate#
Flagship models cost several times more per token than the rest of the catalog. Tying them to an actual payment — rather than to holding a plan — is what stops an account created for a promotion from being worth more than it cost.
A gifted plan is not a payment
An account can hold a paid plan without anyone having paid: trials, referral rewards and promotional grants all do this. Those accounts get full access to free and paid models, and premium stays closed until a real payment lands.
What a blocked call looks like#
Free plan calling a paid model
{
"error": {
"message": "This is a premium model. The Free plan only allows free models — upgrade your plan or top up your wallet to use it.",
"type": "permission_error",
"code": "permission_denied"
}
}Paying account calling a premium model
{
"error": {
"message": "This model requires a paid account. Top up your wallet or subscribe to a plan to unlock it.",
"type": "permission_error",
"code": "permission_denied"
}
}Both are 403. Retrying will not help — the request is valid, the account is not entitled. Surface it to whoever can change the plan rather than looping. See Error codes.
Tiers and degradation#
When xKiro substitutes a model, it never moves you up a tier. A free-tier request cannot be quietly served by a paid model: the entitlement check runs against the model you named, so an upgrade behind the scenes would hand you access you were refused at the door — and bill you for it.
- Substitutes are always equal or lower priced.
- Substitutes never cross from free into paid.
- You are billed at the price of the model you requested, so the direction of substitution can only ever save you money.
Checking your own tier#
GET /v1/models returns what your account can call, so an empty result for a model you expected is an entitlement answer, not a catalog one. Plan details and current balance are in the dashboard.
For what each tier costs and how usage is metered, see Pricing & billing.