[role="xpack"]
[[ml-upgrade-job-model-snapshot]]
= Upgrade model snapshots API
++++
<titleabbrev>Upgrade model snapshots</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-ml-anomaly[{ml-cap}  {anomaly-detect} APIs].
--

Upgrades an {anomaly-detect} model snapshot to the latest major version.

NOTE: From {es} 8.10.0,  a new version number is used to
track the configuration and state changes in the {ml} plugin. This new
version number is decoupled from the product version and will increment
independently.

[[ml-upgrade-job-model-snapshot-request]]
== {api-request-title}

`POST _ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>/_upgrade`

[[ml-upgrade-job-model-snapshot-prereqs]]
== {api-prereq-title}

* Requires the `manage_ml` cluster privilege. This privilege is included in the
`machine_learning_admin` built-in role.
* The upgraded snapshot must have a version matching the previous major version.
* The upgraded snapshot must NOT be the current {anomaly-job} snapshot.

[[ml-upgrade-job-model-snapshot-desc]]
== {api-description-title}

Over time, older snapshot formats are deprecated and removed. {anomaly-jobs-cap}
support only snapshots that are from the current or previous major version.

This API provides a means to upgrade a snapshot to the current major version.
This aids in preparing the cluster for an upgrade to the next major version.

Only one snapshot per {anomaly-job} can be upgraded at a time and the upgraded
snapshot cannot be the current snapshot of the {anomaly-job}.

[[ml-upgrade-job-model-snapshot-path-parms]]
== {api-path-parms-title}

`<job_id>`::
(Required, string)
include::{es-ref-dir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]

`<snapshot_id>`::
(Required, string)
include::{es-ref-dir}/ml/ml-shared.asciidoc[tag=snapshot-id]


[[ml-upgrade-job-model-snapshot-query-parms]]
== {api-query-parms-title}

`timeout`::
(Optional, time) Controls the time to wait for the request to complete. The
default value is 30 minutes.

`wait_for_completion`::
(Optional, boolean) When true, the API won't respond until the upgrade is
complete. Otherwise, it responds as soon as the upgrade task is assigned to a
node. Default is false.

[[ml-upgrade-job-model-snapshot-response-body]]
== {api-response-body-title}

`node`::
  (string) The ID of the assigned node for the upgrade task if it is still running.

`completed`::
  (boolean) When true, this means the task is complete. When false, it is still running.

[[ml-upgrade-job-model-snapshot-example]]
== {api-examples-title}

[source,console]
--------------------------------------------------
POST _ml/anomaly_detectors/low_request_rate/model_snapshots/1828371/_upgrade?timeout=45m&wait_for_completion=true
--------------------------------------------------
// TEST[skip:Kibana sample data]

When the snapshot upgrade starts, you receive the following results:

[source,console-result]
----
{
  "completed" : false,
  "node" : "node-1"
}
----