[role="xpack"]
[[migration-api-upgrade]]
=== Migration Upgrade API

The Migration Upgrade API performs the upgrade of internal indices to make them compatible with the next major version.

Indices need to be upgraded one at a time by submitting a POST request to the
`/_xpack/migration/upgrade/index_name` endpoint:

[source,js]
--------------------------------------------------
POST /_xpack/migration/upgrade/.watches
--------------------------------------------------
// CONSOLE
// TEST[skip:cannot create an old index in docs test]

A successful call returns the statistics about the upgrade process:

[source,js]
--------------------------------------------------
{
  "took" : 127,
  "timed_out" : false,
  "total" : 4,
  "updated" : 0,
  "created" : 4,
  "deleted" : 0,
  "batches" : 1,
  "version_conflicts" : 0,
  "noops" : 0,
  "retries" : {
    "bulk" : 0,
    "search" : 0
  },
  "throttled_millis" : 0,
  "failures" : [ ]
}
--------------------------------------------------
// NOTCONSOLE

By default, the upgrade call blocks until the upgrade process is finished. For large indices the upgrade can be
performed asynchronously by specifying `wait_for_completion=false` parameter:

[source,js]
--------------------------------------------------
POST /_xpack/migration/upgrade/.watches?wait_for_completion=false
--------------------------------------------------
// CONSOLE
// TEST[skip:cannot create an old index in docs test]

This call should return the id of the upgrade process task:

[source,js]
--------------------------------------------------
{
  "task" : "PFvgv7T6TGumRyFF3vqTFg:1137"
}
--------------------------------------------------
// NOTCONSOLE

The status of the running or finished upgrade requests can be obtained using <<tasks,Task API>>:

[source,js]
--------------------------------------------------
GET _tasks/PFvgv7T6TGumRyFF3vqTFg:1137?detailed=true
--------------------------------------------------
// CONSOLE
// TEST[skip:cannot create an old index in docs test]

[source,js]
--------------------------------------------------
{
  "completed" : true, <1>
  "task" : {
    "node" : "PFvgv7T6TGumRyFF3vqTFg",
    "id" : 1137,
    "type" : "transport",
    "action" : "cluster:admin/xpack/upgrade",
    "description" : "",
    "start_time_in_millis" : 1500650625413,
    "running_time_in_nanos" : 947456819,
    "cancellable" : true
  },
  "response" : { <2>
    "took" : 212,
    "timed_out" : false,
    "total" : 4,
    "updated" : 0,
    "created" : 4,
    "deleted" : 0,
    "batches" : 1,
    "version_conflicts" : 0,
    "noops" : 0,
    "retries" : {
      "bulk" : 0,
      "search" : 0
    },
    "throttled_millis" : 0,
    "failures" : [ ]
  }
}
--------------------------------------------------
// NOTCONSOLE

<1> `true` in the `completed` field indicates that the upgrade request has finished, `false` means that
request is still executing

<2> the `response` field contains the status of the upgrade request