opensearch-docs-cn/_api-reference/tasks.md

---
layout: default
title: Tasks
nav_order: 85
---

# Tasks
Introduced 1.0
{: .label .label-purple }

A task is any operation you run in a cluster. For example, searching your data collection of books for a title or author name is a task. When you run OpenSearch, a task is automatically created to monitor your cluster's health and performance. For more information about all of the tasks currently executing in your cluster, you can use the `tasks` API operation.

The following request returns information about all of your tasks:

```
GET _tasks
```
{% include copy-curl.html %}

By including a task ID, you can get information specific to a particular task. Note that a task ID consists of a node's identifying string and the task's numerical ID. For example, if your node's identifying string is `nodestring` and the task's numerical ID is `1234`, then your task ID is `nodestring:1234`. You can find this information by running the `tasks` operation:

```
GET _tasks/<task_id>
```
{% include copy-curl.html %}

Note that if a task finishes running, it won't be returned as part of your request. For an example of a task that takes a little longer to finish, you can run the [`_reindex`]({{site.url}}{{site.baseurl}}/opensearch/reindex-data) API operation on a larger document, and then run `tasks`.

**Sample Response**
```json
{
  "nodes": {
    "Mgqdm0r9SEGClWxp_RbnaQ": {
      "name": "opensearch-node1",
      "transport_address": "172.18.0.3:9300",
      "host": "172.18.0.3",
      "ip": "172.18.0.3:9300",
      "roles": [
        "data",
        "ingest",
        "master",
        "remote_cluster_client"
      ],
      "tasks": {
        "Mgqdm0r9SEGClWxp_RbnaQ:17416": {
          "node": "Mgqdm0r9SEGClWxp_RbnaQ",
          "id": 17416,
          "type": "transport",
          "action": "cluster:monitor/tasks/lists",
          "start_time_in_millis": 1613599752458,
          "running_time_in_nanos": 994000,
          "cancellable": false,
          "headers": {}
          }
        },
        "Mgqdm0r9SEGClWxp_RbnaQ:17413": {
          "node": "Mgqdm0r9SEGClWxp_RbnaQ",
          "id": 17413,
          "type": "transport",
          "action": "indices:data/write/bulk",
          "start_time_in_millis": 1613599752286,
          "running_time_in_nanos": 172846500,
          "cancellable": false,
          "parent_task_id": "Mgqdm0r9SEGClWxp_RbnaQ:17366",
          "headers": {}
        },
        "Mgqdm0r9SEGClWxp_RbnaQ:17366": {
          "node": "Mgqdm0r9SEGClWxp_RbnaQ",
          "id": 17366,
          "type": "transport",
          "action": "indices:data/write/reindex",
          "start_time_in_millis": 1613599750929,
          "running_time_in_nanos": 1529733100,
          "cancellable": true,
          "headers": {}
        }
      }
    }
  }
}
```

You can also use the following parameters with your query.

Parameter | Data type | Description |
:--- | :--- | :---
`nodes` | List | A comma-separated list of node IDs or names to limit the returned information. Use `_local` to return information from the node you're connecting to, specify the node name to get information from specific nodes, or keep the parameter empty to get information from all nodes.
`actions` | List | A comma-separated list of actions that should be returned. Keep empty to return all.
`detailed` | Boolean | Returns detailed task information. (Default: false)
`parent_task_id` | String | Returns tasks with a specified parent task ID (node_id:task_number). Keep empty or set to -1 to return all.
`wait_for_completion` | Boolean | Waits for the matching tasks to complete. (Default: false)
`group_by` | Enum | Groups tasks by parent/child relationships or nodes. (Default: nodes)
`timeout` | Time | An explicit operation timeout. (Default: 30 seconds)
`master_timeout` | Time | The time to wait for a connection to the primary node. (Default: 30 seconds)

For example, this request returns tasks currently running on a node named `opensearch-node1`:

**Sample Request**

```
GET /_tasks?nodes=opensearch-node1
```
{% include copy-curl.html %}

**Sample Response**

```json
{
  "nodes": {
    "Mgqdm0r9SEGClWxp_RbnaQ": {
      "name": "opensearch-node1",
      "transport_address": "sample_address",
      "host": "sample_host",
      "ip": "sample_ip",
      "roles": [
        "data",
        "ingest",
        "master",
        "remote_cluster_client"
      ],
      "tasks": {
        "Mgqdm0r9SEGClWxp_RbnaQ:24578": {
          "node": "Mgqdm0r9SEGClWxp_RbnaQ",
          "id": 24578,
          "type": "transport",
          "action": "cluster:monitor/tasks/lists",
          "start_time_in_millis": 1611612517044,
          "running_time_in_nanos": 638700,
          "cancellable": false,
          "headers": {}
        },
        "Mgqdm0r9SEGClWxp_RbnaQ:24579": {
          "node": "Mgqdm0r9SEGClWxp_RbnaQ",
          "id": 24579,
          "type": "direct",
          "action": "cluster:monitor/tasks/lists[n]",
          "start_time_in_millis": 1611612517044,
          "running_time_in_nanos": 222200,
          "cancellable": false,
          "parent_task_id": "Mgqdm0r9SEGClWxp_RbnaQ:24578",
          "headers": {}
        }
      }
    }
  }
}
```

The following request will return detailed information about active search tasks:

**Sample Request**

```bash
curl -XGET "localhost:9200/_tasks?actions=*search&detailed
```
{% include copy.html %}

**Sample Response**

```json
{
  "nodes" : {
    "CRqNwnEeRXOjeTSYYktw-A" : {
      "name" : "runTask-0",
      "transport_address" : "127.0.0.1:9300",
      "host" : "127.0.0.1",
      "ip" : "127.0.0.1:9300",
      "roles" : [
        "cluster_manager",
        "data",
        "ingest",
        "remote_cluster_client"
      ],
      "attributes" : {
        "testattr" : "test",
        "shard_indexing_pressure_enabled" : "true"
      },
      "tasks" : {
        "CRqNwnEeRXOjeTSYYktw-A:677" : {
          "node" : "CRqNwnEeRXOjeTSYYktw-A",
          "id" : 677,
          "type" : "transport",
          "action" : "indices:data/read/search",
          "description" : "indices[], search_type[QUERY_THEN_FETCH], source[{\"query\":{\"query_string\":<QUERY_STRING>}}]",
          "start_time_in_millis" : 1660106254525,
          "running_time_in_nanos" : 1354236,
          "cancellable" : true,
          "cancelled" : false,
          "headers" : { },
          "resource_stats" : {
            "total" : {
              "cpu_time_in_nanos" : 0,
              "memory_in_bytes" : 0
            }
          }
        }
      }
    }
  }
}

```

## Task canceling

After getting a list of tasks, you can cancel all cancelable tasks with the following request:

```
POST _tasks/_cancel
```
{% include copy-curl.html %}

Note that not all tasks are cancelable. To see if a task is cancelable, refer to the `cancellable` field in the response to your `tasks` API request.

You can also cancel a task by including a specific task ID.

```
POST _tasks/<task_id>/_cancel
```
{% include copy-curl.html %}

The `cancel` operation supports the same parameters as the `tasks` operation. The following example shows how to cancel all cancelable tasks on multiple nodes.

```
POST _tasks/_cancel?nodes=opensearch-node1,opensearch-node2
```
{% include copy-curl.html %}

## Attaching headers to tasks

To associate requests with tasks for better tracking, you can provide a `X-Opaque-Id:<ID_number>` header as part of the HTTPS request reader of your `curl` command. The API will attach the specified header in the returned result.

Usage:

```bash
curl -i -H "X-Opaque-Id: 111111" "https://localhost:9200/_tasks" -u 'admin:admin' --insecure
```
{% include copy.html %}

The `_tasks` operation returns the following result.

```json
HTTP/1.1 200 OK
X-Opaque-Id: 111111
content-type: application/json; charset=UTF-8
content-length: 768

{
  "nodes": {
    "Mgqdm0r9SEGClWxp_RbnaQ": {
      "name": "opensearch-node1",
      "transport_address": "172.18.0.4:9300",
      "host": "172.18.0.4",
      "ip": "172.18.0.4:9300",
      "roles": [
        "data",
        "ingest",
        "master",
        "remote_cluster_client"
      ],
      "tasks": {
        "Mgqdm0r9SEGClWxp_RbnaQ:30072": {
          "node": "Mgqdm0r9SEGClWxp_RbnaQ",
          "id": 30072,
          "type": "direct",
          "action": "cluster:monitor/tasks/lists[n]",
          "start_time_in_millis": 1613166701725,
          "running_time_in_nanos": 245400,
          "cancellable": false,
          "parent_task_id": "Mgqdm0r9SEGClWxp_RbnaQ:30071",
          "headers": {
            "X-Opaque-Id": "111111"
          }
        },
        "Mgqdm0r9SEGClWxp_RbnaQ:30071": {
          "node": "Mgqdm0r9SEGClWxp_RbnaQ",
          "id": 30071,
          "type": "transport",
          "action": "cluster:monitor/tasks/lists",
          "start_time_in_millis": 1613166701725,
          "running_time_in_nanos": 658200,
          "cancellable": false,
          "headers": {
            "X-Opaque-Id": "111111"
          }
        }
      }
    }
  }
}
```
This operation supports the same parameters as the `tasks` operation. The following example shows how you can associate `X-Opaque-Id` with specific tasks:

```bash
curl -i -H "X-Opaque-Id: 123456" "https://localhost:9200/_tasks?nodes=opensearch-node1" -u 'admin:admin' --insecure
```
{% include copy.html %}