OpenSearch/docs/reference/cluster/tasks.asciidoc

[[tasks]]
== Task Management API

experimental[The Task Management API is new and should still be considered experimental.  The API may change in ways that are not backwards compatible]

[float]
=== Current Tasks Information

The task management API allows to retrieve information about the tasks currently
executing on one or more nodes in the cluster.

[source,js]
--------------------------------------------------
GET /_tasks <1>
GET /_tasks?nodes=nodeId1,nodeId2 <2>
GET /_tasks?nodes=nodeId1,nodeId2&actions=cluster:* <3>
--------------------------------------------------
// AUTOSENSE

<1> Retrieves all tasks currently running on all nodes in the cluster.
<2> Retrieves all tasks running on nodes `nodeId1` and `nodeId2`.  See <<cluster-nodes>> for more info about how to select individual nodes.
<3> Retrieves all cluster-related tasks running on nodes `nodeId1` and `nodeId2`.

The result will look similar to the following:

[source,js]
--------------------------------------------------
{
  "nodes" : {
    "oTUltX4IQMOUUVeiohTt8A" : {
      "name" : "Tamara Rahn",
      "transport_address" : "127.0.0.1:9300",
      "host" : "127.0.0.1",
      "ip" : "127.0.0.1:9300",
      "tasks" : {
        "oTUltX4IQMOUUVeiohTt8A:124" : {
          "node" : "oTUltX4IQMOUUVeiohTt8A",
          "id" : 124,
          "type" : "direct",
          "action" : "cluster:monitor/tasks/lists[n]",
          "start_time_in_millis" : 1458585884904,
          "running_time_in_nanos" : 47402,
          "parent_task_id" : "oTUltX4IQMOUUVeiohTt8A:123"
        },
        "oTUltX4IQMOUUVeiohTt8A:123" : {
          "node" : "oTUltX4IQMOUUVeiohTt8A",
          "id" : 123,
          "type" : "transport",
          "action" : "cluster:monitor/tasks/lists",
          "start_time_in_millis" : 1458585884904,
          "running_time_in_nanos" : 236042
        }
      }
    }
  }
}

--------------------------------------------------

It is also possible to retrieve information for a particular task, or all children of a particular
tasks using the following two commands:

[source,js]
--------------------------------------------------
GET /_tasks/taskId1
GET /_tasks?parent_task_id=parentTaskId1
--------------------------------------------------
// AUTOSENSE

The task API can be also used to wait for completion of a particular task. The following call will
block for 10 seconds or until the task with id `oTUltX4IQMOUUVeiohTt8A:12345` is completed.

[source,js]
--------------------------------------------------
GET /_tasks/oTUltX4IQMOUUVeiohTt8A:12345?wait_for_completion=true&timeout=10s
--------------------------------------------------
// AUTOSENSE


[float]
=== Task Cancellation

If a long-running task supports cancellation, it can be cancelled by the following command:

[source,js]
--------------------------------------------------
POST /_tasks/taskId1/_cancel
--------------------------------------------------
// AUTOSENSE

The task cancellation command supports the same task selection parameters as the list tasks command, so multiple tasks
can be cancelled at the same time. For example, the following command will cancel all reindex tasks running on the
nodes `nodeId1` and `nodeId2`.

[source,js]
--------------------------------------------------
POST /_tasks/_cancel?node_id=nodeId1,nodeId2&actions=*reindex
--------------------------------------------------
// AUTOSENSE


[float]
=== Task Grouping

The task lists returned by task API commands can be grouped either by nodes (default) or by parent tasks using the `group_by` parameter.
The following command will change the grouping to parent tasks:

[source,js]
--------------------------------------------------
GET /_tasks?group_by=parents
--------------------------------------------------
// AUTOSENSE