Date-based versions for the Compute Engine API: the partial success default changes

Scripts that list the VMs in a project each night and reconcile them against an inventory, or monitoring that looks for VMs someone forgot to stop, can be built with the Compute Engine API call that lists all zones at once (aggregatedList). In that case, a temporary problem in any one zone can make the list retrieval itself fail. Conversely, a setting that avoids failure returns a list with some zones missing. Which behavior you get is determined by the API's default and how you call it.

According to the release notes, the "versions specified by date" of the Compute Engine API became generally available on September 29, 2026, and they were announced in detail on the official blog on November 5, 2026. The existing /v1 can still be used as is, but the new versions change this list's default, among other things. Based on official materials and the editorial team's comparison of the Discovery documents for each version and the Python library, this article lays out what to check in existing automation.

How dated versions work

According to the blog, the Compute Engine API has so far been offered in three tracks: /v1 (generally available), /beta, and /alpha. Now, alongside these, versions named after dates are being added. The documentation calls this approach interface-based versioning (IBV).

• Stable versions (YYYY-MM-DD): Released quarterly, with 2026-09-01 as the first version. No breaking changes are made after release, and there is currently no end-of-support date
• Preview versions (YYYY-MM-DD-preview): Branched from stable versions and released at shorter intervals. The term is one year, and the first version is 2026-10-01-preview. Compatibility is not guaranteed, and the documentation does not recommend use in critical production environments
• /v1: Remains fully supported and is still the default when no version is specified. However, the documentation says that new features offered in dated versions cannot be used from /v1

The version is specified not in the URL path but with the HTTP header X-Goog-Api-Version or the query parameter $apiVersion. The path stays /compute/v1/, so the form of a resource's selfLink does not change either. Inside double quotes in a shell, $apiVersion is expanded as a variable, so the documentation instructs you to write %24apiVersion.

What changes in the new versions

The blog says the following points change, or can be changed, in dated versions.

1. Overall lists default to partial success. In /v1, aggregatedList has a returnPartialSuccess default of false, so a temporary problem in a single zone can make the whole call fail. In the new versions, partial success becomes the default. The release notes also say that aggregatedList in 2026-09-01 returns partial results by default when some scopes are unreachable, and that returnPartialSuccess is no longer available on the aggregatedList and list methods
2. Errors become machine-readable. They are aligned to a format that puts the reason, domain, and accompanying information in google.rpc.ErrorInfo. One example given is returning the list of available versions when a nonexistent version is specified
3. IAM permission checks can be made stricter. Conventional permission checks that were too broad in scope can be narrowed in the new versions
4. Old resource definitions can be cleaned up. This opens a way to move them, version by version, to a form that follows the API design guidelines (AIP)

The specific changes listed in the release notes are, for 2026-09-01, the partial success in item 1. For 2026-10-01-preview, quotas is removed from the responses of projects.get, regions.get, and regions.list, and the notes direct you to the Cloud Quotas API for checking quotas.

Comparing the Discovery document for each version

The blog says that a Discovery document can be retrieved for each version. On November 5, 2026, the editorial team retrieved the Discovery documents that are available without authentication, changing the version. When we retrieved them again on November 6, the figures below were the same.

• version=2026-09-01 and version=2026-10-01-preview could be retrieved, and version=2099-01-01 returned "Discovery document not found" (404)
• In all three, basePath is /compute/v1/, and the revision is 20261026
• The method counts are 1,018 for /v1, 1,019 for 2026-09-01, and 1,092 for 2026-10-01-preview. The preview version has 73 methods that are not in the stable version
• The returnPartialSuccess parameter present on 203 methods in /v1 (list 120, aggregatedList 53, and so on) is entirely gone in 2026-09-01

The last point matches the blog's "partial success by default" and the release notes' "returnPartialSuccess is no longer available". In the new versions, there is no parameter for choosing partial success in the first place. On the other hand, in the 2026-09-01 Discovery document and REST reference as well, the description of aggregatedList still contained the old sentence recommending that you set returnPartialSuccess to true to prevent failures. The definition and description are out of sync, so it is safer not to judge from the description alone. Note that what the release notes say returns partial results by default is aggregatedList; they do not mention the behavior of list.

The path to watch: where the version changes automatically

Scripts that call the API directly over HTTP stay on /v1 unless they specify a version in a header or query. The paths that need attention are those where the library or tool decides the version. The table in the blog says the following.

In other words, even without changing a single line of code, list retrieval may switch to partial success when you upgrade a library or Terraform provider. The blog does not say which release is tied to which version.

The Python library has switched as of 1.55.0

So we compared the PyPI distributions of the Python client library (google-cloud-compute). Up to 1.54.0 from September 17, 2026, there was no logic to send a version header, and the official releases from 1.55.0 on October 1 through 1.57.0 on November 5 contain logic to send 2026-09-01.

The editorial team installed and ran 1.54.0 and 1.57.0 in a test virtual environment and, without connecting to the API, checked only what aggregated_list was going to send.

Code that explicitly set partial success to avoid failures will raise an exception when building the request once the library is upgraded. The distributions from 1.55.0 onward have no definition of this parameter. The Node.js 7.9.0 distribution and the source on Go's main branch also contained logic to send 2026-09-01. We have not been able to confirm which version the Terraform providers send.

What to check in existing automation (editorial proposal)

1. Identify the callers. List whether your VM listing, inventory, and shutdown automation calls the API through direct HTTP, client libraries, gcloud, or Terraform. Also note the library and provider versions
2. Do not discard partial success results. The aggregatedList response has unreachables, which indicates the scopes that could not be retrieved (it is in the definitions of both /v1 and 2026-09-01). Before changing versions, add logic that raises a warning when it is not empty. The most dangerous outcome is concluding "there are no VMs" without noticing a missing zone
3. Try it with the header in a test environment. Before production, run the same processing with X-Goog-Api-Version: 2026-09-01 added and compare the counts and the form of errors
4. Treat library updates as version updates. Even for automated dependency update PRs, merge Compute Engine libraries and providers only after confirming the version they are tied to. Also search for places that specify return_partial_success and remove them before updating

For how to think about permissions when having an AI agent operate gcloud, see our article on permission design for remote MCP. For getting Terraform operations in order, also see our article on OpenTofu and Terraform.

Scope of verification

On November 5, 2026, we retrieved the announcement on the official Google Cloud blog (published the same day) and checked it against the original text. On November 6, we also checked against the Compute Engine release notes, the API versions guide, the explanation of how to build requests, and the REST reference for 2026-09-01 (document research). In addition, we retrieved the Compute Engine Discovery documents (/v1, 2026-09-01, 2026-10-01-preview) without authentication and compared methods and parameters. We ran Python library versions 1.54.0 and 1.57.0 on Python 3.15.0 on macOS 26.5.1 and checked what they send without connecting to the API (hands-on testing). We did not make any API calls requiring authentication, so the actual responses for partial success, how parameters not in the definition are handled when sent directly over HTTP, and the actual contents of ErrorInfo are unconfirmed. We also have not confirmed which version the Terraform providers send, or libraries other than Python, Node.js, and Go, such as Java.

For reviews of cloud automation and infrastructure configuration management, please contact us through consultation on development, AI, and automation.

References

• Introducing Compute Engine API multi-versioning（Google Cloud Blog）
• Compute Engine release notes
• Compute Engine API versioning guide
• Creating API requests and handling responses
• google-cloud-compute（PyPI）
• Compute Engine Discovery document（v1）
• Compute Engine Discovery document（2026-09-01）