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
```
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:
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`.
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.
`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
```
**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": {}
}
}
}
}
}
```
## Task canceling
After getting a list of tasks, you can cancel all cancelable tasks with the following request:
```
POST _tasks/_cancel
```
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
```
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
```
## 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.
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:
