elasticsearch/docs/reference/cluster/nodes-usage.asciidoc

[[cluster-nodes-usage]]
=== Nodes feature usage API
++++
<titleabbrev>Nodes feature usage</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-cluster[Cluster APIs].
--

Returns information on the usage of features.

[[cluster-nodes-usage-api-request]]
==== {api-request-title}

`GET /_nodes/usage` +

`GET /_nodes/<node_id>/usage` +

`GET /_nodes/usage/<metric>` +

`GET /_nodes/<node_id>/usage/<metric>`

[[cluster-nodes-usage-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the `monitor` or
`manage` <<privileges-list-cluster,cluster privilege>> to use this API.

[[cluster-nodes-usage-api-desc]]
==== {api-description-title}

The cluster nodes usage API allows you to retrieve information on the usage
of features for each node. All the nodes selective options are explained
<<cluster-nodes,here>>.


[[cluster-nodes-usage-api-path-params]]
==== {api-path-parms-title}

`<metric>`::
    (Optional, string) Limits the information returned to the specific metrics.
    A comma-separated list of the following options:
+
--
    `_all`::
        Returns all stats.

    `rest_actions`::
        Returns the REST actions classname with a count of the number of times
        that action has been called on the node.
--

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=node-id]


[[cluster-nodes-usage-api-query-params]]
==== {api-query-parms-title}

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=timeout-nodes-request]


[[cluster-nodes-usage-api-example]]
==== {api-examples-title}

Rest action example:

[source,console]
--------------------------------------------------
GET _nodes/usage
--------------------------------------------------
// TEST[setup:node]

The API returns the following response:

[source,console-result]
--------------------------------------------------
{
  "_nodes": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "cluster_name": "my_cluster",
  "nodes": {
    "pQHNt5rXTTWNvUgOrdynKg": {
      "timestamp": 1492553961812, <1>
      "since": 1492553906606, <2>
      "rest_actions": {
        "nodes_usage_action": 1,
        "create_index_action": 1,
        "document_get_action": 1,
        "search_action": 19, <3>
        "nodes_info_action": 36
      },
      "aggregations": {
        ...
      }
    }
  }
}
--------------------------------------------------
// TESTRESPONSE[s/"my_cluster"/$body.cluster_name/]
// TESTRESPONSE[s/"pQHNt5rXTTWNvUgOrdynKg"/\$node_name/]
// TESTRESPONSE[s/1492553961812/$body.$_path/]
// TESTRESPONSE[s/1492553906606/$body.$_path/]
// TESTRESPONSE[s/"rest_actions": [^}]+}/"rest_actions": $body.$_path/]
// TESTRESPONSE[s/"aggregations": [^}]+}/"aggregations": $body.$_path/]
<1> Timestamp for when this nodes usage request was performed.
<2> Timestamp for when the usage information recording was started. This is
equivalent to the time that the node was started.
<3> Search action has been called 19 times for this node.