Detecting Model Retirement from the API - Anthropic lifecycle, OpenAI shutdown_date, Amazon Bedrock modelLifecycle, and Gemini API Rerouting

First Published: 2026-10-20
Last Updated: 2026-10-20

Companies that provide models gradually retire older models. The dates for these retirements are listed on each company's deprecations pages, and this site's calendar also collects these dates. However, there are times when you may want to programmatically determine if a model ID used by your application is approaching retirement, without having to manually check those pages. Much of that information is in the responses from each company's Models API.

This article presents a table comparing what each of four companies – Anthropic, OpenAI, Google (Gemini API and Gemini Enterprise Agent Platform), and Amazon Bedrock – returns regarding model retirement through their Models APIs. Anthropic returns lifecycle, deprecated_at, and retires_at. OpenAI returns shutdown_date. Amazon Bedrock returns modelLifecycle. No field for status or retirement date was found in the models.list response from the Gemini API. On the Gemini API, for some models, the model_status in the response to a generation request holds the model's stage and retirement time. The Gemini API also routes requests for some IDs that are headed for retirement to a different model.

This article also highlights two additional points. First, the term "deprecated" has different meanings depending on the company. Second, it describes what happens when you make requests to an ID after its retirement date. Some companies state that requests will fail, while for others, requests are routed to a different model. This article does not provide a comprehensive list of dates, nor does it address pricing. It also refrains from evaluating which company's approach is preferable.

The information presented in this article was checked on October 19, 2026. On October 20, 2026, this article called each of the four APIs once and recorded the returned values in chapter 7. The values recorded represent the responses received from a single organization and account on that specific day.

Related articles on this site:

1. Scope and Assumptions
2. How to Read the Tables
3. Lifecycle Words Differ by Vendor
4. What Each Models API Returns
5. What Happens After the Date
6. Building a Check That Does Not Rely on a Calendar
7. What This Article's Calls Returned
8. Failure Modes
9. Frequently Asked Questions About Detecting Model Retirement from the API
10. Summary
11. References

1. Scope and Assumptions

This section defines the intended audience, outlines the scope of this article, shows the scheduling differences across platforms, and lists the sources read. The key takeaways, presented in advance, are as follows:

Anthropic: The Models API's lifecycle field is the retirement signal. The possible values are active, deprecated, and retired. By default, the list returns only active and deprecated models. The documentation says that a past retires_at date does not mean that the model is retired. However, in this article's calls, the API returned active for a model that the deprecations page lists as Deprecated (section 7.2).
OpenAI: OpenAI's deprecations page instructs users to monitor the shutdown_date field in the GET /v1/models endpoint. In this article's calls, model IDs whose shutdown date had passed still appeared in the list and still displayed a past shutdown_date. The one ID that this article sent an inference request to, gpt-5.1-chat-latest, returned a 404 error (section 7.3).
Gemini API: No field for status or retirement date was found on the Model returned by models.list. For some models, the response to a generation request (GenerateContentResponse) holds the model's stage and retirement time in its model_status field (section 4.3). The Gemini API's deprecations page says that requests to gemini-3.7-flash are automatically routed to gemini-3.8-flash, and requests to gemini-3.5-flash to gemini-3.6-flash. In this article's calls, the response's model_version field held the ID of the model that the request was routed to (section 7.4). The Gemini Enterprise Agent Platform page lists a retirement date of January 28, 2027, for the same gemini-3.7-flash model.
Amazon Bedrock: The responses of ListFoundationModels and GetFoundationModel include a modelLifecycle field that indicates the model's status. The status field can have two values: ACTIVE and LEGACY. There is no value for EOL (end of life). The Legacy version of the model lifecycle page says that the status can differ by Region. In this article's calls, the EOL model cohere.command-r-v1:0 was absent from the list, and both GetFoundationModel and an inference request returned a ResourceNotFoundException (section 7.5).
What stays with you: You are responsible for periodically retrieving the list and comparing it to the previous results, retrieving data for each Region individually, consulting the pages and changelog where no field was found, and comparing the model ID in the response to the model ID in the request.

1.1 Intended Readers

This article is intended for the following audience:

Individuals responsible for applications that use multiple model providers (Claude API, OpenAI, Gemini API, Amazon Bedrock).
Developers who want to detect model retirement through APIs, rather than relying on a calendar.
Those who assume one of the four statements below

The four statements are:

A model is usable if its ID appears in the response to a GET /v1/models request.
Requests for IDs whose retirement date has passed will always fail.
All providers return retirement information in the response from their Models API.
The status of a model in Bedrock is consistent across all Regions.

None of these assumptions align with the information found in the documentation or the results obtained by this article. Anthropic's list includes models marked as deprecated by default. In this article's calls, OpenAI's list also returned IDs whose shutdown date had passed. Anthropic's Models API documentation says that a past date in the retires_at field does not mean that a model is retired. The Gemini API routes requests to some IDs that are headed for retirement instead of failing them. No status field was found in the Gemini API's Model response. Bedrock's documentation indicates that the status of a model can vary by Region.

1.2 What This Article Covers and What It Does Not

This article covers the retirement fields of the four vendors' Models APIs, the defaults and filters of their lists, how their lifecycle words line up, what happens after the retirement date, and how to build a check.

This article does not cover:

A list of retirement dates. This site's AI Model Deprecation and Lifecycle Calendar holds it.
Procedures for migrating to new models, and how to adjust prompts. For Claude, this site's Anthropic Claude Model Migration Guide holds it.
Lists of errors. This site's Anthropic Claude API Errors Reference and Amazon Bedrock Errors and Exceptions Reference hold them.
Pricing and billing.
Comparisons of model performance, or which provider's approach is superior.
The shutdowns of OpenAI products (Agent Builder, Evals platform, reusable prompts). This is a separate topic from model retirement, covered in a related article on this site, Before OpenAI's Agent Builder, Evals, and Reusable Prompts Shut Down.
Lists of Regions. This information is available on the Bedrock and Agent Platform pages.

1.3 The Same Model Can Retire on Different Dates by Platform

The same model can retire on different dates on different platforms. Keep this in mind when reading the tables in this article.

Anthropic's model deprecations page describes the scope of its dates as follows:

The dates on this page apply to Anthropic-operated platforms: the Claude API, Claude Platform on AWS, and Microsoft Foundry. Partner-operated platforms (Amazon Bedrock and Google Cloud) set their own retirement schedules, so a model's lifecycle status and dates can differ.

Similarly, the model lifecycle page of the Amazon Bedrock user guide says the same thing from Bedrock's side.

Model lifecycle dates are specific to Amazon Bedrock and may differ from dates published by model providers (such as Anthropic or Cohere). For Amazon Bedrock usage, only the dates on the model card apply.

The same situation occurs with Google. The Gemini API's deprecations page gives gemini-3.7-flash no shutdown date and says that requests to it are routed to gemini-3.8-flash. The model versions page for Gemini Enterprise Agent Platform, however, gives a retirement date of January 28, 2027, for the same gemini-3.7-flash model. This article does not combine the Gemini API and Agent Platform.

This article's calls also found the same Anthropic model in different states on two platforms (section 7.5). claude-opus-4-1-20250805 is retired on the Claude API, and a request to it returned a 404 error. In Bedrock, anthropic.claude-opus-4-1-20250805-v1:0 is marked as LEGACY, with an endOfLifeTime of January 8, 2027.

1.4 Sources Read and the Check Date

This article is based on a review of the following documents, conducted on October 19, 2026:

Anthropic: Pages for the Models API (list and retrieve), model deprecations, errors, models overview, release notes, the anthropic-sdk-python CHANGELOG, and the messages.py and model_info.py source files.
OpenAI: Pages for deprecations, the Models API reference, the OpenAPI specification from GitHub's openai/openai-openapi repository, the Model type and CHANGELOG for openai-python, and the error codes page. On October 20, 2026, this article also read the Model type of openai-python versions 3.0.0 and 3.1.0 and the commit for version 3.1.0.
Google: Pages for Gemini API deprecations and changelog, the models REST reference, the types for python-genai, and the model versions page of Gemini Enterprise Agent Platform. On October 20, 2026, this article also read the Gemini API Discovery document (revision 20261019).
AWS: The ListFoundationModels, GetFoundationModel, and FoundationModelLifecycle pages of the Bedrock API reference, two pages from the user guide regarding model lifecycle (the page for models released on or after September 7, 2026, and the Legacy version for models released before that date), model cards for Cohere Command R and other models, the DescribeServiceLifecycle API reference and SDK examples from AWS Health, and the What's New post on the AWS Health version catalog.

Rows are added to the tables on the deprecations pages from day to day. The rows and dates that this article gives are the values on the check date. For a list of dates, see this site's calendar article.

2. How to Read the Tables

This section defines the columns and words used in this article's tables.

2.1 Common Columns

The tables in this article use the following six column headings. The first five columns are common to two related articles on this site, while the final column, Lifecycle Words, is specific to this article.

Column	What the cell holds
`Platform Provides`	What the platform emits, accepts, or commits to, in the words of its documentation
`Where You Read It`	The page, Console screen, or API field where the value or state can be read
`If You Do Nothing`	What happens with the defaults, including rejection, truncation, and disabling
`No Statement Found`	What the documentation does not state, with the sources searched
`What Stays With You`	What the platform does not take over and remains the user's responsibility
`Lifecycle Words`	The vendor's state words in its own spelling, and what each one still allows

2.2 Wording Conventions

This article writes state words in English, in the exact spellings of each company's documentation. Anthropic's deprecated, OpenAI's deprecated, the Gemini API's deprecation, and Bedrock's LEGACY do not have the same meaning. When it writes a state word, this article places the company name in the same sentence.

If a specific statement cannot be found in the documentation, this article writes No statement found and names the sources searched in the same cell or sentence. This article does not say that the feature does not exist. When this article combines statements in the documentation to reach a conclusion, it calls that an inference.

This article distinguishes four dates: the announcement date (the date each company announced the deprecation), the planned date (represented by terms like retires_at, shutdown_date, or endOfLifeTime), the check date (the date this article read the documentation), and the release date of the version (the date the SDK version was released).

2.3 Documented Values and the Values This Article's Calls Returned

The tables in chapters 3 through 6 contain only documented values. Where the text in those chapters mentions a result of this article's calls, it says so and points to chapter 7. Chapter 7 presents the values that this article got by calling the APIs. These values represent the results of calling each API once, with one organization or account, on October 20, 2026. It is not guaranteed that the same values will be returned for other organizations or on different dates.

3. Lifecycle Words Differ by Vendor

This chapter outlines what the four companies call the stages leading to retirement, and what is possible at each stage.

3.1 Anthropic

Anthropic's model deprecations page uses four words for the stages of a model.

Active: The model is fully supported and recommended for use.
Legacy: The model will no longer receive updates and may be deprecated in the future.
Deprecated: The model is still functional but no longer recommended. Anthropic provides a recommended replacement and assigns a retirement date.
Retired: The model is no longer available for use. Requests to retired models will fail.

The lifecycle value in the Models API can be active, deprecated, or retired. Of the four words on the page, Legacy has no matching lifecycle value. The Models API page defines deprecated and retired as follows:

deprecated: The model remains callable for organizations with existing access, but is headed for retirement and closed to new adopters.
retired: The model is no longer available for use; inference requests naming it fail. It remains in the catalogue as the historical record of its retirement.

For Anthropic, deprecated means that while organizations currently using the model can still access it, it is no longer available for new users to begin using. The page says that, for publicly released models, Anthropic notifies the customers who use a model of its retirement with at least 60 days' notice.

3.2 OpenAI

OpenAI's deprecations page defines deprecated, shut down, and legacy as follows:

When we announce that a model or endpoint is being deprecated, it immediately becomes deprecated. All deprecated models and endpoints will also have a shut down date. At the time of the shut down, the model or endpoint will no longer be accessible.

We use the terms "sunset" and "shut down" interchangeably to mean a model or endpoint is no longer accessible.

We use the term "legacy" to refer to models and endpoints that no longer receive updates.

OpenAI's deprecated starts at the announcement and always comes with a shut down date. After the shut down date, the model can no longer be used. Legacy is a separate word, meaning that updates have stopped.

The same page also specifies the minimum period between the announcement and the shut down. For generally available (GA) models, this period is at least six months. For specialized versions of GA models, the minimum period is at least three months. Preview models, whose names contain preview, may be retired within a much shorter timeframe, such as two weeks. In some cases, this timeframe may be shortened due to safety or compliance reasons.

3.3 Gemini API and Gemini Enterprise Agent Platform

The Gemini API deprecations page defines deprecation and shutdown as follows:

A "deprecation" is the announcement that we no longer provide support for a model, and that it will be "shut down" in the near future. Once a model is "shutdown", it is completely turned off, and the endpoint is no longer available.

In the table on that page, the rows for gemini-3.7-flash and gemini-3.5-flash have N/A in the shutdown date column. The "Recommended replacement" column for the gemini-3.7-flash row states:

gemini-3.8-flash (not available to select in Google AI Studio; the endpoint is not shutting down and automatically routes API requests to gemini-3.8-flash)

The row for gemini-3.5-flash has the same form, and its requests are routed to gemini-3.6-flash. The two IDs are routed to different models. The Gemini API changelog, in its October 8, 2026 entry, says that both IDs are deprecated and that requests to them are automatically routed.

So on the Gemini API, some deprecated IDs have a shutdown date and others are routed instead of being shut down. The page also has the following note on the shutdown dates in the table.

The shutdown dates listed in the table indicate the earliest possible dates on which a model might be retired.

The Gemini API has one more set of state words: the model_stage in the model_status of the response to a generation request (section 4.3). The python-genai types describe three of its values as follows:

LEGACY: If the model is on this stage, it means that this model is on the path to deprecation in near future. Only existing customers can use this model.
DEPRECATED: Models in this stage are deprecated. These models cannot be used.
RETIRED: Models in this stage are retired. These models cannot be used.

On the deprecations page, deprecation refers to the announcement. The model_stage value DEPRECATED refers to a stage in which the model cannot be used. Even within the Gemini API, the two words do not point to the same stage. This article does not say that either one is wrong.

The Gemini API Discovery document (revision 20261019) also marks the model_stage values UNSTABLE_EXPERIMENTAL and DEPRECATED as themselves deprecated (enumDeprecated).

The Gemini Enterprise Agent Platform has a separate policy from the Gemini API. The model versions page gives gemini-3.7-flash a retirement date of January 28, 2027, and the replacement gemini-3.8-flash. The same page says that it does not move retirement dates earlier.

While retirement timelines may be extended, they won't be moved to an earlier date than what is listed.

Within what this article read, no statement on automatic routing of requests was found on the Agent Platform page.

3.4 Amazon Bedrock

The Amazon Bedrock user guide's model lifecycle page describes the policies for models released on Bedrock on or after September 7, 2026. Models released prior to that date are covered in the Legacy version of the page. The current page outlines three states.

Every model on Amazon Bedrock has one of three states: Active, Legacy, or End-of-Life (EOL).

On the Legacy stage, the page says:

Once the Legacy period begins, new customers can't adopt the model, and existing customers may lose access after 15 days of inactivity.

On EOL, the current page says:

After the EOL date, the model is removed from all AWS Regions and requests made to it will fail, unless there is a private arrangement between you and the provider for continued access.

The API values do not match the three states on the page. The FoundationModelLifecycle page of the API reference gives only two values for status:

Valid Values: ACTIVE | LEGACY

That same reference describes ACTIVE as available and LEGACY as deprecated. What Bedrock's API calls deprecated is the Legacy stage on the page. There is no corresponding status value for EOL.

3.5 How the Words Line Up

The following table lists terms used by the four companies and Agent Platform. Terms in the same row do not necessarily have identical meanings.

Platform	`Lifecycle Words`	Existing users can still call it	New users can start
Anthropic (page)	Active / Legacy / Deprecated / Retired	Yes until Retired (Deprecated: still functional)	No statement found (model deprecations page)
Anthropic (`lifecycle`)	`active` / `deprecated` / `retired`	`deprecated`: yes, for organizations with existing access	`deprecated`: no
OpenAI	deprecated (from the announcement) / shut down (= sunset) / legacy (no updates)	Yes until the shut down date	No statement found (deprecations page)
Gemini API	deprecation / shutdown (page); `model_stage` in `model_status`: `LEGACY` / `DEPRECATED` / `RETIRED`; some deprecated IDs are routed	Routed IDs: the request is answered by the model that the page names; `LEGACY`: only existing customers	Routed IDs: not selectable in Google AI Studio; `LEGACY`: no
Agent Platform	Retirement date per model version	Yes until the retirement date	No statement found (model versions page)
Amazon Bedrock (page)	Active / Legacy / EOL	Legacy: yes, but may lose access after 15 days of inactivity	Legacy: no
Amazon Bedrock (`status`)	`ACTIVE` / `LEGACY` (no EOL value)	`LEGACY`: as for Legacy	`LEGACY`: as for Legacy

4. What Each Models API Returns

This chapter outlines the fields returned by each company's Models API about retirement, and the defaults of their lists.

4.1 Anthropic's Models API

Anthropic's GET /v1/models and GET /v1/models/{model_id} endpoints return the following three fields for each model.

Field	Type	What the documentation says
`lifecycle`	`active`, `deprecated`, or `retired`	The model's current lifecycle stage
`deprecated_at`	RFC 3339 string or `null`	Time of the most recent deprecation; populated for `deprecated` and `retired`; `null` while `active`
`retires_at`	RFC 3339 string or `null`	Currently scheduled retirement date; `null` while `active` or while no retirement is scheduled

The description for retires_at concludes with two sentences.

The schedule can be revised until retirement occurs; null while the model is active or while no retirement is scheduled. A past date on a deprecated model means retirement is overdue, not that it has occurred: lifecycle is the retirement signal.

What tells you that a model is retired is lifecycle, not the date in retires_at. retires_at represents a planned date and may be subject to change until the model is actually retired.

The list has a lifecycle filter, and its default is as follows:

Filter the list to models in any of the given lifecycle stages (active, deprecated, or retired). Up to 3 values. When omitted, the list contains the active and deprecated models; retired models appear only when retired is requested explicitly.

The default list includes models that are deprecated. To view models that are retired, you must explicitly specify lifecycle as retired.

For when these fields and the filter were added, the source that this article found is the anthropic-sdk-python CHANGELOG. The entry for version 1.12.0 (October 7, 2026) states: add lifecycle stage fields and filter to /v1/models. Within what this article read, no entry for these fields was found in Anthropic's API release notes. The release notes for the Models API during the same period mention the addition of the line field on October 1, 2026, and the addition of the capabilities field on October 5, 2026, and October 6, 2026. Within what this article read, no beta note on lifecycle was found.

4.2 OpenAI's Models

The OpenAI deprecations page opens by telling readers to use the Models API to monitor shutdowns.

To monitor model shutdowns programmatically, call the List models endpoint (GET /v1/models) and check each model’s optional shutdown_date field.

In the OpenAPI specification, the Model object's shutdown_date field can be either a date string or null, and is not a required field. The description states:

The date when the model will shut down, or null if not announced.

The Model object in the OpenAPI specification only includes a single date related to its retirement; there is no field indicating whether it is deprecated. There are no filtering options available for the listModels endpoint, and the description states:

Lists the currently available models, and provides basic information about each one such as the owner and availability.

On the SDK side, the openai-python Model type does not have shutdown_date in version 3.0.0 and has it from version 3.1.0 (August 14, 2026). The body of the commit that the 3.1.0 CHANGELOG entry points to lists optional model shutdown dates among the additions. This is when the SDK added the field, not when the API added it. Within what this article read (the deprecations page, the Models API reference, and the openai-python CHANGELOG), no statement on the date when the API added the field was found.

4.3 Gemini API Models

This article examines the Model fields returned by the models.list and models.get endpoints of the Gemini API, in two sources, the REST reference and the python-genai types. No field for model status or retirement date was found in either source. The Model fields in the REST reference are: name, baseModelId, version, displayName, description, inputTokenLimit, outputTokenLimit, supportedGenerationMethods, thinking, temperature, maxTemperature, topP, and topK. The REST path is v1beta.

This does not mean that the Gemini API offers no way to learn of a retirement. The Gemini API's deprecations page and changelog describe retirement and routing. In addition, the response to a generation request (GenerateContentResponse) has a model_status field. The Gemini API changelog says the following in its January 12, 2026 entry:

Launched model lifecycle feature. Some models will now specify the lifecycle stage and deprecation timeline.

The python-genai types describe model_status on GenerateContentResponse as follows:

Output only. The current model status of this model. This field is not supported in Vertex AI.

The ModelStatus in model_status has three fields: model_stage, retirement_time, and message. The description of retirement_time is The time at which the model will be retired. As the changelog says, only some models specify their stage and timeline. On the Gemini API, the places to detect retirement are the pages and the response to a generation request, not the Models API response. This article's calls did not record model_status (section 7.4). Section 7.4 records a case in which routing showed in the model_version field of an inference response.

4.4 Amazon Bedrock ListFoundationModels and GetFoundationModel

The model lifecycle page says that the state appears in the modelLifecycle field.

You can see the status of a model in the console, and when you make a GetFoundationModel or ListFoundationModels call, the state is shown in the modelLifecycle field in the response.

The API reference for FoundationModelLifecycle includes four timestamp fields in addition to the status field. Only the status field is required.

Field	Required	What the field holds
`status`	Yes	`ACTIVE` or `LEGACY`
`startOfLifeTime`	No	Launch time when the model first becomes available
`legacyTime`	No	Time when the model enters legacy state
`endOfLifeTime`	No	Time when model is no longer available for use in all AWS regions
`publicExtendedAccessTime`	No	Timestamp for the public extended access portion of the legacy period

The ListFoundationModels filtering options are based on provider, customization type, output modality, and inference type. There is no filtering based on status.

Bedrock's status is read on a per-Region basis. The Legacy version of the page, which covers models released before September 7, 2026, says:

Model lifecycle state can differ by AWS Region. The Regions column in the following tables lists only the Regions covered by a model's announced EOL date. A model can remain Active in other Regions, and the absence of a Region from a row doesn't mean the model will stay available there indefinitely. To check the current state for the Region you use, call ListFoundationModels or GetFoundationModel in that Region and read the modelLifecycle field.

4.5 Contract Tables

The following two tables list the four companies and Agent Platform, organized by the columns outlined in section 2.1. The first table has three columns, while the second table has the remaining three columns.

Platform	`Platform Provides`	`Where You Read It`	`Lifecycle Words`
Anthropic	`lifecycle`, `deprecated_at`, `retires_at` on each model; `lifecycle` filter on the list	`GET /v1/models`, `GET /v1/models/{model_id}`; model deprecations page	`active` / `deprecated` / `retired` (page: Active / Legacy / Deprecated / Retired)
OpenAI	Optional `shutdown_date` (date or `null`) on each model	`GET /v1/models`, `GET /v1/models/{model}`; deprecations page	deprecated / shut down / legacy
Gemini API	No state or retirement field found on `Model`; `model_status` (stage and retirement time) on `GenerateContentResponse` for some models; routing of some deprecated IDs	Deprecations page; changelog; `model_status` on responses	deprecation / shutdown (page); `model_stage` values; routed IDs
Agent Platform	Retirement date per model version	Model versions page	Retirement date
Amazon Bedrock	`modelLifecycle` with `status` and up to four times	`ListFoundationModels`, `GetFoundationModel` per Region; model cards	`ACTIVE` / `LEGACY` (page: Active / Legacy / EOL)

Platform	`If You Do Nothing`	`No Statement Found`	`What Stays With You`
Anthropic	Default list includes `deprecated`; `retired` appears only on request	HTTP status and error type for a retired ID (deprecations, errors, and Models API pages)	Reading `lifecycle`, not `retires_at`; asking for `retired` explicitly
OpenAI	No filter; every model in the list, with or without `shutdown_date`	The response shape after shutdown (deprecations page, error codes page)	Comparing `shutdown_date` with today
Gemini API	Requests to routed IDs are answered by `gemini-3.8-flash` or `gemini-3.6-flash`	A state field on `Model` (REST reference, python-genai types)	Watching the deprecations page and changelog; reading `model_status` on responses
Agent Platform	The model version is retired on its date	Automatic routing (model versions page)	Watching the model versions page
Amazon Bedrock	State is per Region; no lifecycle filter on the list	Whether an EOL model stays in the list (API reference, both lifecycle pages)	Calling each Region you use

5. What Happens After the Date

This chapter outlines what happens when a request is made to an ID after its retirement (shut down, EOL) date, within what the documentation says.

5.1 What the Documentation Says Fails

For three of the four vendors and for Agent Platform, the documentation says that requests after the date fail or that the model can no longer be used.

Anthropic: The model deprecations page says Requests to retired models will fail., and the Models API page says inference requests naming it fail
OpenAI: The deprecations page says that at the time of the shut down, the model or endpoint will no longer be accessible
Amazon Bedrock: The model lifecycle page says that after the EOL date requests made to it will fail, and goes on to say migration will not happen automatically
Agent Platform: The model versions page lists a retirement date for each model version, and its migration section refers to the errors caused by models reaching their retirement dates

The Gemini API page also says that a shut-down model is completely turned off. However, as noted in section 5.3, the Gemini API has some IDs that are routed instead of being shut down.

5.2 How Anthropic's Two Pages Phrase It

Anthropic's two pages describe handling requests that have passed their retirement date in different ways. The migration section of the model deprecations page says:

Once a model is deprecated, migrate all usage to a suitable replacement before the retirement date. Requests to models past the retirement date will fail.

On the Models API page, the retires_at field, as described in section 4.1, says that a past date means retirement is overdue, not that it has occurred.

The two pages provide different clues depending on where you read them. If you only look at the date, it suggests that requests past their retirement date will fail. However, in the Models API, the relevant indicator is the lifecycle field, rather than the date in the retires_at field. On the detection side, this article reads the lifecycle field (section 6.1). This article does not say that either page is wrong.

5.3 The Gemini API Reroutes, and Agent Platform Retires on a Date

The Gemini API deprecations page and changelog say that requests to gemini-3.7-flash and gemini-3.5-flash are routed to gemini-3.8-flash and gemini-3.6-flash, respectively. Requests will not fail; instead, a different model will respond. From the application's side, no error is returned.

The Agent Platform's model versions page lists a retirement date of January 28, 2027, for the same gemini-3.7-flash model. Within what this article read, no statement on routing was found on the Agent Platform page. For the same model ID, what happens after the date depends on whether you use it on the Gemini API or on Agent Platform.

5.4 The Amazon Bedrock EOL Exception Message

The model cards for Bedrock contain messages describing the exceptions returned when a request is made to a model that has reached EOL. The card for Cohere Command R states:

Command R reached end of life on August 19, 2026 and is no longer available. Requests to this model fail with ResourceNotFoundException: This model version has reached the end of its life.

The same exception name and message are also found on the cards for Command R+ (August 19, 2026), Llama 3.1 405B Instruct, and Llama 3.2 1B Instruct (July 7, 2026). The card for Claude 3 Haiku states that it reached EOL on September 10, 2026, in most Regions, while in some Regions it is still offered or in the Legacy stage. Not all models reach EOL at the same time in all AWS Regions. The API reference describes endOfLifeTime as Time when model is no longer available for use in all AWS regions. The cards' per-Region wording works at a different level of detail. This article presents both descriptions, without stating that either one is incorrect.

5.5 What No Statement Was Found On

Within what this article read, no statement on the following was found:

Anthropic: The HTTP status and error type that a request to a retired ID returns (sources searched: the model deprecations, errors, and Models API pages). The description for the 404 not_found_error on the errors page is a general sentence: Check the endpoint path and any resource IDs in the request URL. This site's Anthropic Claude API Errors Reference says that a retired model produces a 404. Section 7.2 records that a 404 came back in this article's calls.
OpenAI: The shape of the response that a request returns after a model is shut down (sources searched: the deprecations and error codes pages). The documentation goes as far as no longer be accessible.
Gemini API: Which field of a response shows that the request was routed (sources searched: the deprecations page, the changelog, the models REST reference, and the python-genai types). The description of the model_status type goes as far as the stage, the retirement time, and a message (message).
Amazon Bedrock: Whether EOL models remain in the response from ListFoundationModels (sources searched: the API reference and the two model lifecycle pages). Also, what a request made through an inference profile returns after the EOL date (same sources).

Chapter 7 records what this article's calls returned for the Anthropic, OpenAI, and Gemini API items and for the Bedrock list item.

6. Building a Check That Does Not Rely on a Calendar

This chapter outlines methods for detecting retirement, using the four vendors' fields. The fields to read for OpenAI (specifically, the shutdown_date field) and for Bedrock (the modelLifecycle field for each Region, on the Legacy version of the page) come directly from their respective documentation. However, in the documentation of these four companies that this article read, no page that involved regularly retrieving lists and comparing them with previous results was found. The section of this article detailing that approach was created based on the definitions of the fields. This article has not run this configuration on a real system.

6.1 What to Read and How to Compare

The check in this chapter takes each vendor's list on a schedule and compares it with the last results. The specific information to read and the comparison methods vary for each company.

Platform	What to read	What to compare
Anthropic	`lifecycle` on a list with all three values requested	A model ID that your code uses moving from `active` to `deprecated`, or to `retired`
OpenAI	`shutdown_date` on the list	A date appearing where there was `null`; a date that is earlier than today
Gemini API	Deprecations page and changelog; `model_status` on the responses that your code already receives	A new row or entry naming a model ID that your code uses; a `retirement_time`, or a `model_stage` of `LEGACY`, `DEPRECATED`, or `RETIRED`
Agent Platform	Model versions page	A new retirement date for a model version that your code uses
Amazon Bedrock	`modelLifecycle` in each Region that you use	`status` moving to `LEGACY`; a model ID disappearing from the list

On Anthropic, request all three lifecycle values on the list. Because the default list does not show models marked as retired, when a model ID your code uses is retired, it will appear to disappear from the list. According to the documentation, specifying all three values will cause the retired status to remain visible. However, in this article's calls, retired IDs were not returned even with all three values (section 7.2). So the check in this chapter also treats a model ID disappearing from the list as a change.

On OpenAI, treat it as a change when the shutdown_date changes from null to a date, or when the date is earlier than today. As noted in section 7.3, even after the shutdown date has passed, some IDs remain on the list, so being in the list alone does not tell you whether the model can be used.

6.2 The Default List and a Comparison of ID Sets

Section 8.2 of this site's Anthropic Claude Model Migration Guide provides an example in continuous integration (CI) that compares the model IDs used in the code with the set of IDs returned by the Models API list. This comparison helps identify IDs that have been removed from the list.

Following the addition of the lifecycle field and filtering capabilities to the Models API (anthropic-sdk-python version 1.12.0, October 7, 2026), the default list returns both active and deprecated models. Therefore, when compared with the set of IDs from the default list, retired IDs can be identified, but deprecated IDs will remain in the set and will not be flagged. To detect models in the deprecated state, it is necessary to read the lifecycle status of each individual ID in addition to performing the set comparison.

6.3 SDK Warnings Are Not API Signals

The anthropic-sdk-python library issues warnings on the client-side when deprecated model IDs are passed to a Messages request. A table named DEPRECATED_MODELS exists in src/anthropic/resources/messages/messages.py, and passing any of the IDs listed in this table triggers a DeprecationWarning with the following code.

warnings.warn(
    f"The model '{model}' is deprecated and will reach end-of-life on {DEPRECATED_MODELS[model]}.\nPlease migrate to a newer model. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information.",
    DeprecationWarning,
    stacklevel=3,
)

This table is defined in the SDK's source code and does not reflect API responses. The table in the latest version as of October 19, 2026 (version 1.15.0, released October 15, 2026) gives claude-sonnet-4-5-20250929 the value November 30th, 2026, which matches the model deprecations page. The table gives claude-mythos-preview the value June 30th, 2026, while the page gives its retirement date as To be announced. claude-opus-4-1-20250805, which was retired on August 5, 2026, is not in the table. The table in the SDK contains fixed values specific to each SDK version. This article treats SDK warnings as an aid to detection and uses lifecycle as the signal.

6.4 Filling In Where No Field Was Found

No status field was found in the Gemini API's Models API response. The check in this article watches the Gemini API deprecations page and changelog for changes. It also reads the model_status of the generation responses that the application receives (section 4.3). As the changelog says, only some models show their stage and timeline in this field. For Agent Platform, it watches the model versions page.

Another clue lies in the inference response. As described in section 7.4, when this article requested gemini-3.7-flash, the response's model_version was gemini-3.8-flash. If the model ID in the request differs from the model ID in the response, the request may have been routed. No sentence in the Gemini API documentation that says to detect routing with this comparison was found. This article treats it as one observation.

6.5 AWS Health DescribeServiceLifecycle

AWS Health's DescribeServiceLifecycle API returns information about the lifecycle events for a service version. Examples in the AWS SDK documentation (for Ruby and PHP) show that when service is BEDROCK, the API returns rows with lifecycleEventType values such as STANDARD_SUPPORT_END, EXTENDED_SUPPORT_END, and SUPPORTED. Within what this article read, no specification listing the values that this API returns for Bedrock models was found (in the API reference or SDK examples).

Regarding the version catalog, an AWS What's New post from October 2, 2026, says that this information is visible in the AWS Health Dashboard and that the AWS Health API can incorporate this data for customers with specific support plans.

It is available in the AWS Health Dashboard, and customers on Business Support Plus, Enterprise Support, or Unified Operations can use the AWS Health API to integrate lifecycle data into their operational workflows.

This site's Where AWS Publishes Version End Dates deals with the version catalog and DescribeServiceLifecycle, and excludes Bedrock models in section 3.7. As the way to read the state of Bedrock models by machine, this article reads modelLifecycle first. The AWS Health API provides an additional source of information for customers who meet the requirements of a support plan.

6.6 A Design Example for a Scheduled Check

The following diagram shows this article's design example for a scheduled check. It is not a configuration shown in AWS documentation, and this article has not built it on a real system. EventBridge Scheduler periodically triggers a function, which retrieves each vendor's list, as well as the Bedrock list in each Region you use. The function then compares these with the previous results and sends notifications if any changes are detected. The scheduling expression can be checked with this site's EventBridge cron/rate Expression Validator.

A Scheduled Check That Compares Lists (Design Example)

In this example design, the user is responsible for managing the following: the storage location for each company's API keys, the storage location for the previous results, the list of Bedrock Regions to use, how to watch for changes on the Gemini API and Agent Platform pages, and the migration after a notification. The Bedrock page notes that migration will not happen automatically. The Anthropic page tells users to migrate to the replacement model before the retirement date. The Gemini API changelog indicates that users should update the model string to a new ID, such as gemini-3.8-flash. The Gemini API's routing is not an update of the model string; it sends the request to another model that the page names.

7. What This Article's Calls Returned

This chapter documents the values obtained by this article when calling the APIs of four different companies. These values are kept apart from the documented values in chapters 3 through 6.

7.1 Configuration

Item	Value
Date and time	2026-10-19T21:31Z (2026-10-20 06:31 JST)
Calls	Each call once, from a local Python script; no cloud resources were created
SDKs	`anthropic` 1.15.0, `openai` 3.35.1, `google-genai` 2.31.0, `boto3` 1.43.115
Bedrock Regions	`us-east-1` and `us-west-2`
Account	One organization or account per vendor; values can differ for other organizations

The values presented in this chapter were obtained once, using this configuration. They should not be used for performance comparisons. This article has redacted API keys, organization IDs, request IDs, and AWS account IDs.

7.2 Anthropic

This article called models.list twice (with the defaults, and with the three lifecycle values), models.retrieve twice, and messages.create once.

Call	Result
`models.list` (default)	14 models, all `lifecycle: active`; `deprecated_at` and `retires_at` all `null`
`models.list` with `lifecycle` = `active`, `deprecated`, `retired`	The same 14 models, all `active`; no `deprecated` or `retired` model
`models.retrieve("claude-sonnet-4-5-20250929")`	Returned; `lifecycle: active`, `deprecated_at: null`, `retires_at: null`
`models.retrieve("claude-opus-4-1-20250805")`	HTTP 404, `not_found_error`
`messages.create` with `claude-opus-4-1-20250805`	HTTP 404, `not_found_error`

A request to messages.create for the retired model claude-opus-4-1-20250805 (retired on August 5, 2026, as checked on the page on October 19, 2026) returned the following response:

{"type": "error", "error": {"type": "not_found_error", "message": "model: claude-opus-4-1-20250805"}, "request_id": "<request-id>"}

In this configuration, requests to the retired model ID resulted in a 404 not_found_error, which matches the 404 that this site's errors reference describes. As section 5.5 says, the documentation does not state this status in the context of retirement.

This article's calls disagreed with the documentation in two places. First, the model deprecations page lists claude-sonnet-4-5-20250929 as Deprecated (September 30, 2026) with a retirement date of November 30, 2026. However, this organization's Models API returned lifecycle: active and deprecated_at and retires_at as null. Second, the Models API page states that retired models remain in the catalog. However, the list with retired among the lifecycle values contained no retired ID, and attempting to retrieve claude-opus-4-1-20250805 resulted in a 404 error. This article has not checked the reason for these discrepancies, and no statement was found, within what this article read, on whether the differences come from how each organization sees the data or from a delay in updating. This article does not say which source is wrong.

There are two potential impacts on how detection is configured. Simply waiting for the lifecycle to change to deprecated may result in delays compared to the information presented on the page, so the table on the page should also be consulted. The removal of retired IDs from the list should also be considered a change (section 6.1).

7.3 OpenAI

Call	Result
`models.list`	135 models; 71 with a `shutdown_date`
Shut-down IDs in the list	Present with a past date, for example `gpt-5.1-chat-latest`, `gpt-5-codex`, and `gpt-5.1-codex` with `2026-07-23`, and `babbage-002` with `2026-09-28`
`models.retrieve("gpt-4o-2024-08-06")`	Returned; `shutdown_date: 2027-01-14` (matches the deprecations page)
`models.retrieve("gpt-5.1-chat-latest")`	Returned; `shutdown_date: 2026-07-23`
`responses.create` with `gpt-5.1-chat-latest`	HTTP 404, `invalid_request_error`, code `model_not_found`

A request to gpt-5.1-chat-latest, which was shut down on July 23, 2026, returned the following response:

{"error": {"message": "The model `gpt-5.1-chat-latest` does not exist or you do not have access to it.", "type": "invalid_request_error", "param": null, "code": "model_not_found"}}

In this configuration, IDs whose shutdown dates had passed remained in the list. One of them, gpt-5.1-chat-latest, was also returned by retrieve, but the inference request to it returned a 404 error. The OpenAPI specification describes the list as Lists the currently available models (section 4.2), but being in the list did not mean that the model could be used. It is necessary to check whether the shutdown_date is before the current date.

7.4 Gemini API

Call	Result
`models.list`	63 models; fields seen: `name`, `display_name`, `description`, `version`, `input_token_limit`, `output_token_limit`, `supported_actions`, `thinking`, `temperature`, `max_temperature`, `top_p`, `top_k`, `tuned_model_info`
`gemini-3.7-flash` and `gemini-3.5-flash` in the list	Present
`models.get("gemini-3.7-flash")`	Returned; `version: 3.7-flash-08-2026`; no state field
`generate_content` with `gemini-3.7-flash`	Returned; `model_version: gemini-3.8-flash`; `model_status` not recorded

In this configuration, requests to gemini-3.7-flash were successful, and the response's model_version was gemini-3.8-flash, the model that the request is routed to. Both the list and get calls returned gemini-3.7-flash without a state field. The Models API response did not indicate that the model was deprecated, but the inference response showed the routing. This article's script recorded only model_version and usage_metadata from the inference response and did not record model_status (section 4.3). Whether the response for gemini-3.7-flash carried model_status cannot be told from this article's records.

7.5 Amazon Bedrock

Call	Result
`ListFoundationModels`	`us-east-1`: 123 models (115 `ACTIVE`, 8 `LEGACY`); `us-west-2`: 120 models (115 `ACTIVE`, 5 `LEGACY`)
Fields in `modelLifecycle`	`status`, `startOfLifeTime`, `legacyTime`, `endOfLifeTime`, `publicExtendedAccessTime`
Models in both Regions	108; `status` and `endOfLifeTime` were the same in both Regions
`cohere.command-r-v1:0` (EOL) in the list	Absent in both Regions
`GetFoundationModel("cohere.command-r-v1:0")`	HTTP 404, `ResourceNotFoundException`, in both Regions
`Converse` with `cohere.command-r-v1:0` in `us-east-1`	HTTP 404, `ResourceNotFoundException`
`anthropic.claude-opus-4-1-20250805-v1:0`	`LEGACY`; `endOfLifeTime` 2027-01-08
`anthropic.claude-sonnet-4-5-20250929-v1:0`	`LEGACY`; `legacyTime` 2026-10-08; `endOfLifeTime` 2027-04-08

The EOL cohere.command-r-v1:0 returned the following exception message in two calls:

GetFoundationModel: This model version has reached the end of its life. Use an active model version instead. Refer to the Model lifecycle topic in the AWS documentation for more details.
Converse: This model version has reached the end of its life. Please refer to the AWS documentation for more details.

In this configuration, the EOL model was absent from the list, and both GetFoundationModel and inference returned a 404 ResourceNotFoundException. The first part of the exception message was identical to the model card description. For the 108 models present in both Regions, there was no difference in state. The differences observed were models present in only one of the Regions. This does not contradict the documentation's Model lifecycle state can differ by AWS Region. On that day, in these two Regions, no difference showed up.

For the same Anthropic models, different statuses were observed between the Claude API and Bedrock. The model claude-opus-4-1-20250805 returned a 404 error via the Claude API, while in Bedrock it was listed as LEGACY. The model claude-sonnet-4-5-20250929 was reported as active via the Claude API's Models API, but was marked as LEGACY in Bedrock, effective October 8, 2026. This illustrates the example from section 1.3 regarding differing schedules per platform.

7.6 Reading the Calls Against the Documentation

Platform	What the documentation says	What this article's calls returned
Anthropic	Retired: requests fail; HTTP status not stated	404 `not_found_error` for a retired ID
Anthropic	Default list has `active` and `deprecated`; `retired` stays in the catalog	Only `active` models, even with all three values requested
OpenAI	After shutdown, the model is no longer accessible	Still in the list and retrievable; inference returned 404 `model_not_found`
Gemini API	`gemini-3.7-flash` requests are routed to `gemini-3.8-flash`	`model_version: gemini-3.8-flash` on the response
Amazon Bedrock	After EOL, requests fail; model cards name `ResourceNotFoundException`	Absent from the list; Get and inference returned 404 `ResourceNotFoundException`
Amazon Bedrock	State can differ by Region	No difference among the 108 models found in both Regions on that day

8. Failure Modes

The following are misreadings of this article's tables that lead to errors.

Reading that a model is retired once retires_at has passed: Anthropic's Models API says that a past date in retires_at does not mean that the model is retired. The relevant information is found in the lifecycle field (sections 4.1 and 5.2).
Reading that a model in the default list can be used: Anthropic's default list also returns deprecated models. In this article's calls, OpenAI's list returned IDs whose shutdown dates had passed (sections 4.1 and 7.3).
Reading that comparing ID sets catches deprecated models: In the default list, deprecated IDs stay in the set. Read lifecycle (section 6.2).
Reading that a request always fails after the retirement date: The Gemini API routes requests that name gemini-3.7-flash and gemini-3.5-flash to gemini-3.8-flash and gemini-3.6-flash, respectively. No errors are returned; instead, a different model provides a response (section 5.3).
Reading that Gemini models are never retired: The Agent Platform page lists a retirement date of January 28, 2027, for the same gemini-3.7-flash model. The Gemini API page also says that a shut-down model can no longer be used (section 3.3).
Reading that Gemini offers no way to learn of a retirement: No status field was found on the Model that models.list returns, but the deprecations page and the changelog describe retirements and routing, and the response to a generation request has model_status (section 4.3).
Reading that the Bedrock state from one Region is enough: The documentation says that the state can differ by Region and tells users to read it in the Region they use (section 4.4).
Reading that Bedrock's status shows EOL: The status field has only the values ACTIVE and LEGACY. In this article's calls, the EOL model cohere.command-r-v1:0 was absent from the list (sections 3.4 and 7.5).
Reading that the same model retires on the same date on every platform: The dates on Anthropic's page apply to the platforms that Anthropic operates, while Bedrock and Google Cloud have their own schedules (section 1.3).
Reading that no SDK warning means the model is fine: The SDK's DEPRECATED_MODELS is a table fixed per SDK version, and it can differ from the page (section 6.3).

9. Frequently Asked Questions About Detecting Model Retirement from the API

Q1. On Anthropic, which field tells you through the API that a model you use is headed for retirement?

Read the lifecycle field of the Models API. When the value is deprecated, the model is headed for retirement. The retires_at field gives the planned retirement date, which can change until retirement occurs. A past date does not mean that the model is retired. In this article's calls, the API returned active for a model that the page lists as Deprecated, so watch the model deprecations page as well (sections 4.1 and 7.2).

Q2. What does a request to a retired Anthropic model return?

The documentation states that requests will fail. Within what this article read, no sentence giving the HTTP status and error type in the context of retirement was found. In this article's calls, a 404 not_found_error was returned, with the message indicating model: claude-opus-4-1-20250805 (sections 5.5 and 7.2).

Q3. Can you use every model in OpenAI's list?

Being in the list alone does not tell you. In this article's calls, an ID that was shut down on July 23, 2026, stayed in the list with its past shutdown_date, and a request to it returned 404 model_not_found. Compare the shutdown_date with the current date (section 7.3).

Q4. What happens if you keep using a deprecated model ID on the Gemini API?

It depends on the ID. The Gemini API's deprecations page says that requests to gemini-3.7-flash are automatically routed to gemini-3.8-flash, and requests to gemini-3.5-flash to gemini-3.6-flash. Other IDs with a shutdown date can no longer be used after the shut down. The same gemini-3.7-flash is retired on Agent Platform on January 28, 2027 (sections 3.3 and 5.3).

Q5. Can an application tell that the Gemini API rerouted its request?

In this article's calls, the model_version in the response to the request sent to gemini-3.7-flash was gemini-3.8-flash. There is a possibility that the application could detect the routing by comparing the model ID of the request with the model ID in the response. No sentence in the documentation describing this comparison was found (sections 6.4 and 7.4).

Q6. On Amazon Bedrock, do EOL models appear in ListFoundationModels?

Within what this article read, no statement on whether EOL models are included in the list was found. In this article's calls, the EOL model cohere.command-r-v1:0 was not found in the lists for us-east-1 and us-west-2, and the GetFoundationModel call returned a 404 ResourceNotFoundException (sections 5.5 and 7.5).

Q7. When was this article checked?

This article was checked by reading each company's documentation on October 19, 2026, and by calling each company's API once on October 20, 2026. The tables on the deprecations pages change from day to day. The values in chapter 7 represent the values returned for a single organization and account on that specific day (sections 1.4 and 7.1).

10. Summary

On Anthropic, read lifecycle: The list returns active and deprecated by default, and only returns retired when explicitly requested. A past retires_at date does not mean that the model is retired. In this article's calls, the API returned active for a model that the page lists as Deprecated, while retired IDs returned a 404 error (sections 4.1 and 7.2).
On OpenAI, compare shutdown_date with today: In this article's calls, IDs whose shutdown date had passed stayed in the list, and the inference request to one of them returned 404 (sections 4.2 and 7.3).
On the Gemini API, read the pages and the response: No status field was found on Model. For some models, the model_status in the response to a generation request holds the stage and retirement time. gemini-3.7-flash and gemini-3.5-flash are routed, and the response's model_version field showed the model that the request was routed to. Agent Platform retires the same ID on a date (sections 4.3, 5.3, and 7.4).
On Bedrock, read modelLifecycle in each Region: The status field has only ACTIVE and LEGACY. In this article's calls, the EOL model cohere.command-r-v1:0 was absent from the list, and requests returned ResourceNotFoundException (sections 4.4 and 7.5).
The same model can retire on different dates by platform: A model that was retired on the Claude API was listed as LEGACY on Bedrock (sections 1.3 and 7.5).
The scheduled check and watching the pages where no field was found stay with you: It is also the user's responsibility to migrate model IDs to new models (chapter 6).

11. References

References:
Tech Blog with curated related content

Written by Hidekazu Konishi