elasticsearch/docs/reference/cluster/pending.asciidoc

[[cluster-pending]]
=== Pending cluster tasks API
++++
<titleabbrev>Pending cluster tasks</titleabbrev>
++++

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

Returns cluster-level changes that have not yet been executed.


[[cluster-pending-api-request]]
==== {api-request-title}

`GET /_cluster/pending_tasks`

[[cluster-pending-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `monitor` or
`manage` <<privileges-list-cluster,cluster privilege>> to use this API.

[[cluster-pending-api-desc]]
==== {api-description-title}

The pending cluster tasks API returns a list of any cluster-level changes (e.g. 
create index, update mapping, allocate or fail shard) which have not yet been 
executed.

NOTE: This API returns a list of any pending updates to the cluster state. These are distinct from the tasks reported by the
<<tasks,Task Management API>> which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create
index requests. However, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task
might be reported by both task api and pending cluster tasks API.


[[cluster-pending-api-path-params]]
==== {api-path-parms-title}

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=local]

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]


[[cluster-pending-api-response-body]]
==== {api-response-body-title}

`tasks`::
    (object) A list of pending tasks.
    
`insert_order`::
    (integer) The number that represents when the task has been inserted into 
    the task queue.
    
`priority`::
    (string) The priority of the pending task. The valid priorities in descending priority order are: `IMMEDIATE` > `URGENT` > `HIGH` > `NORMAL` > `LOW` > `LANGUID`. 
    
`source`::
    (string) A general description of the cluster task that may include a reason 
    and origin. 
    
`executing`::
    (boolean) True or false, indicating whether the pending tasks is currently getting executed or not.
    
`time_in_queue_millis`::
    (integer) The time expressed in milliseconds since the task is waiting for 
    being performed.
    
`time_in_queue`::
    (string) The time since the task is waiting for being performed.


[[cluster-pending-api-example]]
==== {api-examples-title}

Usually the request will return an empty list as cluster-level changes are fast. 
However, if there are tasks queued up, the response will look similar like this:

[source,js]
--------------------------------------------------
{
   "tasks": [
      {
         "insert_order": 101,
         "priority": "URGENT",
         "source": "create-index [foo_9], cause [api]",
         "executing" : true,
         "time_in_queue_millis": 86,
         "time_in_queue": "86ms"
      },
      {
         "insert_order": 46,
         "priority": "HIGH",
         "source": "shard-started ([foo_2][1], node[tMTocMvQQgGCkj7QDHl3OA], [P], s[INITIALIZING]), reason [after recovery from shard_store]",
         "executing" : false,
         "time_in_queue_millis": 842,
         "time_in_queue": "842ms"
      },
      {
         "insert_order": 45,
         "priority": "HIGH",
         "source": "shard-started ([foo_2][0], node[tMTocMvQQgGCkj7QDHl3OA], [P], s[INITIALIZING]), reason [after recovery from shard_store]",
         "executing" : false,
         "time_in_queue_millis": 858,
         "time_in_queue": "858ms"
      }
  ]
}
--------------------------------------------------
// NOTCONSOLE
// We can't test tasks output