[DOCS] Document cat tasks API (#47321)

docs/reference/cat.asciidoc

@@ -230,6 +230,8 @@ include::cat/recovery.asciidoc[]
 
 include::cat/repositories.asciidoc[]
 
+include::cat/tasks.asciidoc[]
+
 include::cat/thread_pool.asciidoc[]
 
 include::cat/shards.asciidoc[]

docs/reference/cat/tasks.asciidoc

@@ -0,0 +1,113 @@
+[[cat-tasks]]
+=== cat task management API
+++++
+<titleabbrev>cat task management</titleabbrev>
+++++
+
+beta::[The cat task management API is new and should still be considered a beta feature. The API may change in ways that are not backwards compatible.]
+
+Returns information about tasks currently executing in the cluster,
+similar to the <<tasks,task management>> API.
+
+
+[[cat-tasks-api-request]]
+==== {api-request-title}
+
+`GET /_cat/_tasks/<task_id>`
+
+`GET /_cat/_tasks`
+
+
+[[cat-tasks-api-desc]]
+==== {api-description-title}
+
+The cat task management API returns information
+about tasks currently executing
+on one or more nodes in the cluster.
+It is a more compact view
+of the JSON <<tasks,task management>> API.
+
+
+[[cat-tasks-api-path-params]]
+==== {api-path-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=task-id]
+
+
+[[cat-tasks-api-query-params]]
+==== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=actions]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=detailed]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=http-format]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=group-by]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-h]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=help]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=node-id-query-parm]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=parent-task-id]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_completion]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]
+
+
+[[cat-tasks-api-response-codes]]
+==== {api-response-codes-title}
+
+include::{docdir}/cluster/tasks.asciidoc[tag=tasks-api-404]
+
+
+[[cat-tasks-api-examples]]
+==== {api-examples-title}
+
+
+[[cat-tasks-api-specific-ex]]
+===== Get information for a specific task
+
+[source,console]
+----------------------------------------------------------------------------
+GET _cat/tasks/oTUltX4IQMOUUVeiohTt8A:124?v
+----------------------------------------------------------------------------
+// TEST[skip:No tasks to retrieve]
+
+The API returns the following response:
+
+[source,txt]
+----
+action                         task_id                    parent_task_id             type      start_time    timestamp running_time ip             node
+cluster:monitor/tasks/lists[n] oTUltX4IQMOUUVeiohTt8A:124 oTUltX4IQMOUUVeiohTt8A:123 direct    1458585884904 01:48:24  44.1micros   127.0.0.1:9300 oTUltX4IQMOUUVeiohTt8A
+----
+// TESTRESPONSE[skip:No tasks to retrieve]
+// TESTRESPONSE[non_json]
+
+
+[[cat-tasks-api-all-ex]]
+===== Get information for all tasks in a cluster
+
+[source,console]
+----
+GET _cat/tasks?v
+----
+// TEST[skip:No tasks to retrieve]
+
+The API returns the following response:
+
+[source,console-result]
+----
+action                         task_id                    parent_task_id             type      start_time    timestamp running_time ip             node
+cluster:monitor/tasks/lists[n] oTUltX4IQMOUUVeiohTt8A:124 oTUltX4IQMOUUVeiohTt8A:123 direct    1458585884904 01:48:24  44.1micros   127.0.0.1:9300 oTUltX4IQMOUUVeiohTt8A
+cluster:monitor/tasks/lists    oTUltX4IQMOUUVeiohTt8A:123 -                          transport 1458585884904 01:48:24  186.2micros  127.0.0.1:9300 oTUltX4IQMOUUVeiohTt8A
+----
+// TESTRESPONSE[skip:No tasks to retrieve]
+// TESTRESPONSE[non_json]

docs/reference/cluster/tasks.asciidoc

@@ -1,50 +1,61 @@
 [[tasks]]
-=== Task Management API
+=== Task management API
+++++
+<titleabbrev>Task management</titleabbrev>
+++++
 
-beta[The Task Management API is new and should still be considered a beta feature.  The API may change in ways that are not backwards compatible]
+beta[The task management API is new and should still be considered a beta feature. The API may change in ways that are not backwards compatible.]
 
 Returns information about the tasks currently executing in the cluster.
 
 [[tasks-api-request]]
 ==== {api-request-title}
 
-`GET /_tasks` +
-
 `GET /_tasks/<task_id>`
 
+`GET /_tasks`
+
 
 [[tasks-api-desc]]
 ==== {api-description-title}
 
-The task management API allows to retrieve information about the tasks currently
-executing on one or more nodes in the cluster.
+The task management API returns information
+about tasks currently executing
+on one or more nodes in the cluster.
 
 
 [[tasks-api-path-params]]
 ==== {api-path-parms-title}
 
-`<task_id>`::
-    (Optional, string) The ID of the task to return (`node_id:task_number`).
+include::{docdir}/rest-api/common-parms.asciidoc[tag=task-id]
 
 
 [[tasks-api-query-params]]
 ==== {api-query-parms-title}
 
-include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
+include::{docdir}/rest-api/common-parms.asciidoc[tag=actions]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=detailed]
 
-`wait_for_completion`::
-    (Optional, boolean) If `true`, it waits for the matching tasks to complete. 
-    Defaults to `false`.
+include::{docdir}/rest-api/common-parms.asciidoc[tag=group-by]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=node-id-query-parm]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=parent-task-id]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
 
+include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_completion]
 
     
 [[tasks-api-response-codes]]
 ==== {api-response-codes-title}
 
+tag::tasks-api-404[]
 `404` (Missing resources)::
-    If `{task_id}` is specified but not found, this code indicates that there 
-    are no resources that match the request.
-
+If `<task_id>` is specified but not found, this code indicates that there 
+are no resources that match the request.
+end::tasks-api-404[]
 
 [[tasks-api-examples]]
 ==== {api-examples-title}
@@ -205,18 +216,6 @@ will wait for all `reindex` tasks to finish:
 GET _tasks?actions=*reindex&wait_for_completion=true&timeout=10s
 --------------------------------------------------
 
-
-===== Listing tasks by using _cat
-
-Tasks can be also listed using _cat version of the list tasks command, which
-accepts the same arguments as the standard list tasks command.
-
-[source,console]
---------------------------------------------------
-GET _cat/tasks
-GET _cat/tasks?detailed
---------------------------------------------------
-
 [[task-cancellation]]
 ===== Task Cancellation
 

docs/reference/rest-api/common-parms.asciidoc

@@ -1,4 +1,16 @@
 
+tag::actions[]
+`actions`::
++
+--
+(Optional, string)
+Comma-separated list or wildcard expression
+used to limit the request.
+
+Omit this parameter to return all actions.
+--
+end::actions[]
+
 tag::active-only[]
 `active_only`::
 (Optional, boolean)
@@ -143,11 +155,6 @@ in the `completion_fields` or `fielddata_fields` parameters.
 --
 end::fields[]
 
-tag::generation[]
-Generation number, such as `0`. {es} increments this generation number
-for each segment written. {es} then uses this number to derive the segment name.
-end::generation[]
-
 tag::index-alias-filter[]
 <<query-dsl-bool-query, Filter query>>
 used to limit the index alias.
@@ -174,6 +181,32 @@ tag::from[]
 (Optional, integer) Starting document offset. Defaults to `0`.
 end::from[]
 
+tag::generation[]
+Generation number, such as `0`. {es} increments this generation number
+for each segment written. {es} then uses this number to derive the segment name.
+end::generation[]
+
+tag::group-by[]
+`group_by`::
++
+--
+(Optional, string)
+Key used to group tasks in the response.
+
+Possible values are:
+
+`nodes`::
+(Default)
+Node ID
+
+`parents`::
+Parent task ID
+
+`none`::
+Do not group tasks.
+--
+end::group-by[]
+
 tag::groups[]
 `groups`::
 (Optional, string)
@@ -403,6 +436,27 @@ tag::node-id[]
 returned information.
 end::node-id[]
 
+tag::node-id-query-parm[]
+`node_id`::
+(Optional, string)
+Comma-separated list of node IDs or names
+used to limit returned information.
+end::node-id-query-parm[]
+
+tag::parent-task-id[]
+`parent_task_id`::
++
+--
+(Optional, string)
+Parent task ID
+used to limit returned information.
+
+To return all tasks,
+omit this parameter
+or use a value of `-1`.
+--
+end::parent-task-id[]
+
 tag::pipeline[]
 `pipeline`::
 (Optional, string) ID of the pipeline to use to preprocess incoming documents.
@@ -572,6 +626,12 @@ include::{docdir}/indices/create-index.asciidoc[tag=index-name-reqs]
 --
 end::target-index[]
 
+tag::task-id[]
+`<task_id>`::
+(Optional, string) ID of the task to return
+(`node_id:task_number`).
+end::task-id[]
+
 tag::terminate_after[]
 `terminate_after`::
 (Optional, integer) The maximum number of documents to collect for each shard,