[[cat-nodes]]
=== cat nodes API
++++
<titleabbrev>cat nodes</titleabbrev>
++++

Returns information about a cluster's nodes.

[[cat-nodes-api-request]]
==== {api-request-title}

`GET /_cat/nodes`

[[cat-nodes-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.

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

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=bytes]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=http-format]

`full_id`::
(Optional, Boolean) If `true`, return the full node ID. If `false`, return the
shortened node ID. Defaults to `false`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-h]
+
--
If you do not specify which columns to include, the API returns the default columns in the order listed below. If you explicitly specify one or more columns, it only returns the specified columns.

Valid columns are:

`ip`, `i`::
(Default) IP address, such as `127.0.1.1`.

`heap.percent`, `hp`, `heapPercent`::
(Default) Maximum configured heap, such as `7`.

`ram.percent`, `rp`, `ramPercent`::
(Default) Used total memory percentage, such as `47`.

`file_desc.percent`, `fdp`, `fileDescriptorPercent`::
(Default) Used file descriptors percentage, such as `1`.

`node.role`, `r`, `role`, `nodeRole`::
(Default) Roles of the node. Returned values include
`c` (cold node),
`d` (data node),
`f` (frozen node),
`h` (hot node),
`i` (ingest node),
`l` (machine learning node),
`m` (master-eligible node),
`r` (remote cluster client node),
`s` (content node),
`t` ({transform} node),
`v` (voting-only node),
`w` (warm node), and
`-` (coordinating node only).
+
For example, `dim` indicates a master-eligible data and ingest node. See
<<modules-node>>.

`master`, `m`::
(Default) Indicates whether the node is the elected master node. Returned values
include `*` (elected master) and `-` (not elected master).

`name`, `n`::
(Default) Node name, such as `I8hydUG`.

`id`, `nodeId`::
ID of the node, such as `k0zy`.

`pid`, `p`::
Process ID, such as `13061`.

`port`, `po`::
Bound transport port, such as `9300`.

`http_address`, `http`::
Bound http address, such as `127.0.0.1:9200`.

`version`, `v`::
Elasticsearch version, such as {version}.

`build`, `b`::
Elasticsearch build hash, such as `5c03844`.

`jdk`, `j`::
Java version, such as `1.8.0`.

`disk.total`, `dt`, `diskTotal`::
Total disk space, such as `458.3gb`.

`disk.used`, `du`, `diskUsed`::
Used disk space, such as `259.8gb`.

`disk.avail`, `d`, `disk`, `diskAvail`::
Available disk space, such as `198.4gb`.

`disk.used_percent`, `dup`, `diskUsedPercent`::
Used disk space percentage, such as `47`.

`heap.current`, `hc`, `heapCurrent`::
Used heap, such as `311.2mb`.

`ram.current`,`rc`, `ramCurrent`::
Used total memory, such as `513.4mb`.

`ram.max`, `rm`, `ramMax`::
Total memory, such as `2.9gb`.

`file_desc.current`, `fdc`, `fileDescriptorCurrent`::
Used file descriptors, such as `123`.

`file_desc.max`, `fdm`, `fileDescriptorMax`::
Maximum number of file descriptors, such as `1024`.

`cpu`::
Recent system CPU usage as percent, such as `12`.

`load_1m`, `l`::
Most recent load average, such as `0.22`.

`load_5m`, `l`::
Load average for the last five minutes, such as `0.78`.

`load_15m`, `l`::
Load average for the last fifteen minutes, such as `1.24`.

`uptime`, `u`::
Node uptime, such as `17.3m`.

`completion.size`, `cs`, `completionSize`::
Size of completion, such as `0b`.

`fielddata.memory_size`, `fm`, `fielddataMemory`::
Used fielddata cache memory, such as `0b`.

`fielddata.evictions`, `fe`, `fielddataEvictions`::
Fielddata cache evictions, such as `0`.

`query_cache.memory_size`, `qcm`, `queryCacheMemory`::
Used query cache memory, such as `0b`.

`query_cache.evictions`, `qce`, `queryCacheEvictions`::
Query cache evictions, such as `0`.

`query_cache.hit_count`, `qchc`, `queryCacheHitCount`::
Query cache hit count, such as `0`.

`query_cache.miss_count`, `qcmc`, `queryCacheMissCount`::
Query cache miss count, such as `0`.

`request_cache.memory_size`, `rcm`, `requestCacheMemory`::
Used request cache memory, such as `0b`.

`request_cache.evictions`, `rce`, `requestCacheEvictions`::
Request cache evictions, such as `0`.

`request_cache.hit_count`, `rchc`, `requestCacheHitCount`::
Request cache hit count, such as `0`.

`request_cache.miss_count`, `rcmc`, `requestCacheMissCount`::
Request cache miss count, such as `0`.

`flush.total`, `ft`, `flushTotal`::
Number of flushes, such as `1`.

`flush.total_time`, `ftt`, `flushTotalTime`::
Time spent in flush, such as `1`.

`get.current`, `gc`, `getCurrent`::
Number of current get operations, such as `0`.

`get.time`, `gti`, `getTime`::
Time spent in get, such as `14ms`.

`get.total`, `gto`, `getTotal`::
Number of get operations, such as `2`.

`get.exists_time`, `geti`, `getExistsTime`::
Time spent in successful gets, such as `14ms`.

`get.exists_total`, `geto`, `getExistsTotal`::
Number of successful get operations, such as `2`.

`get.missing_time`, `gmti`, `getMissingTime`::
Time spent in failed gets, such as `0s`.

`get.missing_total`, `gmto`, `getMissingTotal`::
Number of failed get operations, such as `1`.

`indexing.delete_current`, `idc`, `indexingDeleteCurrent`::
Number of current deletion operations, such as `0`.

`indexing.delete_time`, `idti`, `indexingDeleteTime`::
Time spent in deletions, such as `2ms`.

`indexing.delete_total`, `idto`, `indexingDeleteTotal`::
Number of deletion operations, such as `2`.

`indexing.index_current`, `iic`, `indexingIndexCurrent`::
Number of current indexing operations, such as `0`.

`indexing.index_time`, `iiti`, `indexingIndexTime`::
Time spent in indexing, such as `134ms`.

`indexing.index_total`, `iito`, `indexingIndexTotal`::
Number of indexing operations, such as `1`.

`indexing.index_failed`, `iif`, `indexingIndexFailed`::
Number of failed indexing operations, such as `0`.

`merges.current`, `mc`, `mergesCurrent`::
Number of current merge operations, such as `0`.

`merges.current_docs`, `mcd`, `mergesCurrentDocs`::
Number of current merging documents, such as `0`.

`merges.current_size`, `mcs`, `mergesCurrentSize`::
Size of current merges, such as `0b`.

`merges.total`, `mt`, `mergesTotal`::
Number of completed merge operations, such as `0`.

`merges.total_docs`, `mtd`, `mergesTotalDocs`::
Number of merged documents, such as `0`.

`merges.total_size`, `mts`, `mergesTotalSize`::
Size of current merges, such as `0b`.

`merges.total_time`, `mtt`, `mergesTotalTime`::
Time spent merging documents, such as `0s`.

`refresh.total`, `rto`, `refreshTotal`::
Number of refreshes, such as `16`.

`refresh.time`, `rti`, `refreshTime`::
Time spent in refreshes, such as `91ms`.

`script.compilations`, `scrcc`, `scriptCompilations`::
Total script compilations, such as `17`.

`script.cache_evictions`, `scrce`, `scriptCacheEvictions`::
Total compiled scripts evicted from cache, such as `6`.

`search.fetch_current`, `sfc`, `searchFetchCurrent`::
Current fetch phase operations, such as `0`.

`search.fetch_time`, `sfti`, `searchFetchTime`::
Time spent in fetch phase, such as `37ms`.

`search.fetch_total`, `sfto`, `searchFetchTotal`::
Number of fetch operations, such as `7`.

`search.open_contexts`, `so`, `searchOpenContexts`::
Open search contexts, such as `0`.

`search.query_current`, `sqc`, `searchQueryCurrent`::
Current query phase operations, such as `0`.

`search.query_time`, `sqti`, `searchQueryTime`::
Time spent in query phase, such as `43ms`.

`search.query_total`, `sqto`, `searchQueryTotal`::
Number of query operations, such as `9`.

`search.scroll_current`, `scc`, `searchScrollCurrent`::
Open scroll contexts, such as `2`.

`search.scroll_time`, `scti`, `searchScrollTime`::
Time scroll contexts held open, such as `2m`.

`search.scroll_total`, `scto`, `searchScrollTotal`::
Completed scroll contexts, such as `1`.

`segments.count`, `sc`, `segmentsCount`::
Number of segments, such as `4`.

`segments.memory`, `sm`, `segmentsMemory`::
Memory used by segments, such as `1.4kb`.

`segments.index_writer_memory`, `siwm`, `segmentsIndexWriterMemory`::
Memory used by index writer, such as `18mb`.

`segments.version_map_memory`, `svmm`, `segmentsVersionMapMemory`::
Memory used by version map, such as `1.0kb`.

`segments.fixed_bitset_memory`, `sfbm`, `fixedBitsetMemory`::
Memory used by fixed bit sets for nested object field types and type filters for
types referred in <<parent-join,`join`>> fields, such as `1.0kb`.

`suggest.current`, `suc`, `suggestCurrent`::
Number of current suggest operations, such as `0`.

`suggest.time`, `suti`, `suggestTime`::
Time spent in suggest, such as `0`.

`suggest.total`, `suto`, `suggestTotal`::
Number of suggest operations, such as `0`.
--

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=help]

`local`::
(Optional, boolean) 
deprecated:[7.6.0,This parameter does not cause this API to act locally. It will be removed in version 8.0.]
If `true`, the request computes the list of selected nodes from the local
cluster state. Defaults to `false`, which means the list of selected nodes is
computed from the cluster state on the master node. In either case the
coordinating node sends a request for further information to each selected
node.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-s]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=time]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-v]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=include-unloaded-segments]

[[cat-nodes-api-example]]
==== {api-examples-title}

[[cat-nodes-api-ex-default]]
===== Example with default columns

[source,console]
--------------------------------------------------
GET /_cat/nodes?v=true
--------------------------------------------------

The API returns the following response:

[source,txt]
--------------------------------------------------
ip        heap.percent ram.percent cpu load_1m load_5m load_15m node.role master name
127.0.0.1           65          99  42    3.07                  dim       *      mJw06l1
--------------------------------------------------
// TESTRESPONSE[s/3.07/(\\d+\\.\\d+( \\d+\\.\\d+ (\\d+\\.\\d+)?)?)?/]
// TESTRESPONSE[s/65          99  42/\\d+ \\d+ \\d+/]
// TESTRESPONSE[s/dim/.+/ s/[*]/[*]/ s/mJw06l1/.+/ non_json]

The `ip`, `heap.percent`, `ram.percent`, `cpu`, and `load_*` columns provide the
IP addresses and performance information of each node.

The `node.role`, `master`, and `name` columns provide information useful for
monitoring an entire cluster, particularly large ones.


[[cat-nodes-api-ex-headings]]
===== Example with explicit columns
The following API request returns the `id`, `ip`, `port`, `v` (version), and `m`
(master) columns.

[source,console]
--------------------------------------------------
GET /_cat/nodes?v=true&h=id,ip,port,v,m
--------------------------------------------------

The API returns the following response:

["source","txt",subs="attributes,callouts"]
--------------------------------------------------
id   ip        port  v         m
veJR 127.0.0.1 59938 {version} *
--------------------------------------------------
// TESTRESPONSE[s/veJR/.+/ s/59938/\\d+/ s/[*]/[*]/ non_json]
