--- layout: default title: Tasks API nav_order: 25 --- # Tasks API operation 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: ``` GET _tasks/ ``` 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 ``` **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//_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:` 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 ``` 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 ```