---
title: "Preview a cluster upgrade"
method: GET
path: "/clusters/{cluster_id}/upgrade-preview"
tags: ["Cluster Operations"]
---

# Preview a cluster upgrade

`GET /clusters/{cluster_id}/upgrade-preview`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/clusters/{cluster_id}/upgrade-preview`
- Auth: API key in header `API-Key`

Returns breaking changes and per-extension jar plans for upgrading this cluster to the requested target version.

Required scope: `clusters:read`

## Path parameters

- `cluster_id` string, uuid, required

## Query parameters

- `to` string, required: Cluster version in semver format. Check the documentation for the latest supported versions.

## Headers

- `API-Version` '2026-06-01.beta', required

## Response `200`

The request has succeeded.

- ClusterUpgradePreviewResponse: Breaking changes and per-extension jar plans for upgrading a cluster to a target version.
  - `breaking_changes` ClusterVersionBreakingChange[], required: Breaking changes between the cluster's current version and the requested target.
    - `title` string, required: Title of the change, as published in the migration guide.
    - `summary` string, required: Plain-language summary of what changes.
    - `severity` string, required: How disruptive the change is: `breaking`, `config-change` or `deprecation`.
    - `action_required` string, nullable, required: Concrete steps to take before upgrading, or `null` when none are recorded.
  - `extensions` ClusterUpgradeExtensionPlanItem[], required: Installed extensions and how their jars participate in the upgrade.
    - `name` string, required: Extension display name.
    - `action` string, required: Planned action: `will_update`, `unchanged`, `pinned`, `custom`, `no_compatible_build`, or `pinned_no_compatible_build`.
    - `message` string: Customer-facing detail for this row.
    - `current_jar_url` string: Primary JAR URL currently installed, when known.
    - `target_jar_url` string: Primary JAR URL that would be used on the target Keycloak version, when applicable.

## Other responses

- `401`: Access is unauthorized.
- `404`: The server cannot find the requested resource.
- `429`: Client error
- `500`: Server error
- `501`: Server error

---

[API](https://skmtc.dev/skycloak/apis/skycloak-public-api.md) · [All operations](https://skmtc.dev/skycloak/apis/skycloak-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skycloak/apis/skycloak-public-api/revisions/33a69e2ce35f?raw)