Skip to main content
The Gloo AI catalog changes as providers ship new models and retire old ones. Both ends of that lifecycle are visible in GET /platform/v2/models, so you can detect additions and deprecations programmatically instead of watching for an announcement. Production-Ready in the AI Learning Center includes a short script that checks your models for deprecations. Model Updates lists every model added, retired or redirected so far, with dates. Catalog models serve different purposes. The Responses API and Completions V2 API use models that generate answers. The Embeddings API uses embedding models to turn text into vectors. A model is available on its corresponding API once it appears in the catalog. When a Responses or Completions model is deprecated and a replacement is chosen, requests may continue to be routed to that replacement while you migrate. With embeddings, switching models requires re-embedding stored content because vectors from different models are not interchangeable.

New models

Gloo AI tracks provider releases automatically, and new models are usually added to the catalog within a business day or two of a provider making them generally available. Once listed, generation models are usable on the Responses API and Completions V2; embedding models are usable on the Embeddings API. Check output_modalities in the catalog to identify the model type.

Where to find available models

  • Supported Models — a live table of the current catalog, grouped by family, with context windows, list pricing, and capability flags.
  • GET /platform/v2/models — the public, unauthenticated endpoint the table is built from. Call it to enumerate models; poll it to detect additions. Use each entry’s id field as your model parameter.
  • Model Explorer in Gloo Studio — a richer side-by-side comparison including modalities, reasoning, and speed ratings.
All three read from the same catalog, so they always agree. Use the endpoint to automate against, the table to scan, and the Explorer to compare.

Model ID naming

Gloo model IDs follow a consistent, human-readable pattern:
For example: Always take the exact ID from the catalog’s id field rather than constructing it by hand: the naming pattern is a convention, not a guarantee.

Model families

Every model carries a family field that groups it by provider or model line, for example Anthropic, Google, OpenAI, and Open Source, alongside other families as new providers are added. The Supported Models table is organized by this field, and it is returned on every GET /platform/v2/models entry so you can filter or route by family in your own code.

Adopting a new model

For generation, switching to a newly available model usually means setting model to its catalog ID, after checking its capabilities, context window, and modalities. For embeddings, use a model whose output_modalities includes embeddings. Keep the same model and dimensions for document and query vectors. Changing either requires re-embedding stored content before querying it with the new vectors. You can try a new model before changing any code: pick it from the model dropdown in the Chat Playground in Gloo AI Studio and send it a prompt. A newly added model is selectable there as soon as it is listed in the catalog. Playground requests run through your organization’s credentials and are billed at standard rates.
Watching GET /platform/v2/models programmatically is the most reliable way to learn about new models as soon as they land.

Deprecated models

Models are occasionally retired as providers release newer, better, or cheaper alternatives. Retirement is the provider’s decision, so we make a best effort to turn it into a managed transition rather than a silent break: where we can, a deprecated model ID keeps serving requests and the catalog tells you what replaces it, so you have time to migrate.
This is not a guarantee. A provider can withdraw a model faster than any notice period; when that happens, the catalog shows what replaces it, if anything. The catalog is the authoritative signal, so check is_deprecated on the models you use.

How deprecations are announced

Deprecations are surfaced on the catalog itself. Each GET /platform/v2/models entry carries:
  • is_deprecated: true once a model is scheduled for retirement.
  • deprecation_note: a plain-language explanation, including the replacement and any price change. Read it: this is where a price increase is stated.
  • replacement_model: the Gloo model ID that requests are routed to.
The Supported Models table also renders a Deprecated badge and the note inline for any flagged model.

Where a deprecated ID’s requests go

For generation models, requests still using a deprecated ID go to the named replacement_model, so they keep working while you migrate. Do not assume this applies to embedding requests: changing an embedding model changes the vector space, and stored content must be re-embedded before using the replacement. When replacement_model is null, nothing is redirected; see When nothing replaces a model.

Response headers on a redirected request

When a request is served by a replacement, the response’s model names the replacement, and a successful (2xx) response also carries these headers, so your client or gateway can spot the redirect without comparing model against what you sent: The same headers mark a retired image model in the image_generation tool. A tool that names gpt-image-1, which OpenAI retired on October 23, 2026, runs on gpt-image-2, and the response carries X-Gloo-Model-Redirected-From: gpt-image-1, Deprecation: true, and Sunset: Fri, 23 Oct 2026 00:00:00 GMT. See Image generation tool. Log or alert on X-Gloo-Model-Redirected-From, then update the model in your requests.

When nothing replaces a model

Occasionally a provider withdraws a model and nothing from the same maker can replace it. Rather than move its requests to an unrelated model, it retires without a replacement. The model is flagged deprecated with no replacement_model, and it may already be gone from GET /platform/v2/models while it keeps serving until its retirement date. Your requests tell you the date.
  • Until the retirement date, requests are still served, and a successful response carries Deprecation: true and Sunset with the date. There is no X-Gloo-Model-Redirected-From, because nothing was redirected. As with any model no longer listed (Notice before removal), don’t build on this: migrate as soon as you see these headers or the entry leaves the catalog.
  • From 00:00 UTC on the retirement date, requests are refused with 410 Gone and the code model_retired, whichever ID you use for the model. The message names the model and says what to use instead. retryable is false: change the model before sending the request again.
For example (message shortened):
On the direct endpoints the response also carries X-Gloo-Error-Code: model_retired. Treat a Sunset header without X-Gloo-Model-Redirected-From as the signal to move before the date.

How a replacement is chosen

Choosing a replacement is best effort: these are the criteria we apply, not promises about an outcome the provider controls.
  • The replacement comes from the same maker. For models deprecated from November 2026 on, we look first for a newer version of the same model, then for the maker’s closest current model. If nothing from the maker qualifies, the model retires with no replacement; see When nothing replaces a model. A few models deprecated earlier still route to another maker’s model, and their deprecation_note names it; Model Updates lists them.
  • Capability should not go backwards. We look for a model that supports everything the deprecated one did (tool calling, vision, reasoning, its input modalities) with a context window at least as large. If the only replacement from the maker has a smaller context window, deprecation_note says so.
  • Price stays within a band. A replacement’s price is normally capped at 1.3× the deprecated model’s rate on either the input or the output axis; any exception is stated in deprecation_note.
Many models also declare their successor in advance, and where that exists it is used directly rather than recomputed. Check replacement_model and deprecation_note for the model your requests will go to. Same-or-cheaper is the ordinary outcome, and each deprecation_note states any exception. Model Updates lists every replacement so far and how its price compares.
A replacement can cost more per token than the model it replaced. It happens when nothing same-or-cheaper from the same maker clears the capability bar, and it is normally capped at 1.3× on each axis; deprecation_note states any increase and any exception. If you bill through on token cost, read it when a model you use is flagged.

Notice before removal

Once a model is flagged as deprecated and its replacement routing is in place, its catalog entry is intended to stay listed for at least a week before it can be removed, so both the old ID and its replacement are live and interchangeable while you migrate. Routing for a retired ID is intended to outlive its catalog entry, but the catalog is the contract: an ID you can still see in GET /platform/v2/models is supported, and one that has been removed is not. Treat continued routing after removal as a courtesy rather than something to build on.

What you should do

1

Watch the catalog

Poll GET /platform/v2/models and check the is_deprecated flag on the models you use. This is the earliest and most reliable signal.
2

Read the replacement

When a model you depend on is deprecated, read its replacement_model and deprecation_note to see where its traffic is routed and whether the price changes. An empty replacement_model means no replacement was chosen, and the choice is yours.
3

Migrate your model ID

Update the model parameter in your requests to the replacement ID. Migrating keeps your configuration accurate and lets you validate the replacement on your own timeline, rather than relying on automatic routing indefinitely.
You don’t have to migrate the moment a generation model is flagged; automatic routing keeps your integration running. Migrating keeps your requests pointed at a model ID that is still listed and actively maintained.

Next steps

To pin a model and move to a replacement on your own schedule, see Choosing, Pinning and Updating Models. Build a Resilient Client shows a client that logs when a deprecated model was redirected.

Supported Models

Current model IDs, capabilities, and pricing.

Model Updates

Every model added, retired or redirected, with dates and replacements.

Provider Failover

How requests behave when a provider is unavailable.