List models
What your workspace can run, how much context each model holds, and what it costs per million tokens.
modelConfig.modelId on a variation, this is where you find out what exists and what it costs.
Prices are cents, as strings
inputPricePerMillionTokens and outputPricePerMillionTokens are cents per million tokens, serialized as strings because they are 64-bit integers.
maxInputTokens drives compaction
A variation’s compactionConfig.triggerThreshold is a fraction of this number, not an absolute token count. The same 0.75 threshold means 750,000 tokens on a million-token model and 150,000 on a 200,000-token one.
That is the trap when you swap models: the threshold moves with the model, and nothing warns you.
maxInputTokens never triggers compaction at all, so a long objective on it grows until it fails.
The prefix filter matches names, not IDs
When you already know which model you want, skip the filter and fetch it directly. GET /models/{id} takes the external_id: form:
modelConfig.modelId. Cadenya resolves it and stores the canonical model_... ID, so a variation reads back with the canonical one.
What a model record holds
Enabled and disabled
A model must beSTATE_ENABLED for a variation to reference it, and the two guards hold each other up:
- Creating or updating a variation onto a disabled model is a
400onspec.model_id. - Disabling a model while any variation references it is a
400.
Related
Create a variation
modelConfig.modelId and temperature are set.Swap models on variations
List context windows
Get objective diagnostics
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Workspace ID.
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Query Parameters
Maximum number of results to return
Pagination cursor from previous response
Filter by a prefix of the model's display name, external id, or id (case-insensitive). A model's external id is the form used in modelConfig.modelId, so a caller holding that can narrow the list by it.
Free-form search query
Filter by model state
STATE_UNSPECIFIED, STATE_ENABLED, STATE_DISABLED Filter to models provisioned on a specific AI provider key. Accepts the key's id or an "external_id:"-prefixed slug.
Filter models to only ones assigned to an active agent variation/agent. Draft agents count as assigned; archived agents do not. Assignment does not imply recent traffic — see ModelInfo.last_used_at for that.
Filters by metadata labels. Comma-separated key=value pairs, e.g. "env=prod,team=ai". A resource matches only if every pair matches exactly (AND semantics).
Sort order for results (asc or desc by creation time)
When true, populate each item's info (e.g. the AI provider), at the cost of extra lookups.