This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.
cat nodes API
editcat nodes API
editcat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.
Returns information about a cluster’s nodes.
Request
editGET /_cat/nodes
Prerequisites
edit-
If the Elasticsearch security features are enabled, you must have the
monitorormanagecluster privilege to use this API.
Query parameters
edit-
bytes - (Optional, byte size units) Unit used to display byte values.
-
format - (Optional, string) Short version of the HTTP accept header. Valid values include JSON, YAML, etc.
-
full_id -
(Optional, Boolean) If
true, return the full node ID. Iffalse, return the shortened node ID. Defaults tofalse. -
h -
(Optional, string) Comma-separated list of column names to display.
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) Used percentage of total allocated Elasticsearch JVM heap, such as
7. This reflects only the Elasticsearch process running within the operating system and is the most direct indicator of its JVM/heap/memory resource performance. -
heap.max,hm,heapMax -
Total heap, such as
4gb. -
ram.percent,rp,ramPercent -
(Default) Used percentage of total operating system’s memory, such as
47. This reflects all processes running on operating system instead of only Elasticsearch and is not guaranteed to correlate to its performance. -
file_desc.percent,fdp,fileDescriptorPercent -
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,
dimindicates a master-eligible data and ingest node. See Nodes. -
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 8.16.0.
-
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 -
(Default) Recent system CPU usage as percent, such as
12. -
load_1m,l -
(Default) Most recent load average, such as
0.22. -
load_5m,l -
(Default) Load average for the last five minutes, such as
0.78. -
load_15m,l -
(Default) 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
joinfields, such as1.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. -
shard_stats.total_count,sstc,shards,shardStatsTotalCount - Number of shards assigned.
-
mappings.total_count,mtc,mappingsTotalCount - Number of mappings, including runtime and object fields.
-
mappings.total_estimated_overhead_in_bytes,mteo,mappingsTotalEstimatedOverheadInBytes - Estimated heap overhead, in bytes, of mappings on this node, which allows for 1KiB of heap for every mapped field.
-
-
help -
(Optional, Boolean) If
true, the response includes help information. Defaults tofalse. -
master_timeout -
(Optional, time units)
Period to wait for the master node. If the master node is not available before
the timeout expires, the request fails and returns an error. Defaults to
30s. Can also be set to-1to indicate that the request should never timeout. -
s - (Optional, string) Comma-separated list of column names or column aliases used to sort the response.
-
time - (Optional, time units) Unit used to display time values.
-
v -
(Optional, Boolean) If
true, the response includes column headings. Defaults tofalse. -
include_unloaded_segments -
(Optional, Boolean) If
true, the response includes information from segments that are not loaded into memory. Defaults tofalse.
Examples
editExample with default columns
editresp = client.cat.nodes(
v=True,
)
print(resp)
response = client.cat.nodes( v: true ) puts response
const response = await client.cat.nodes({
v: "true",
});
console.log(response);
GET /_cat/nodes?v=true
The API returns the following response:
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
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.
Example with explicit columns
editThe following API request returns the id, ip, port, v (version), and m
(master) columns.
resp = client.cat.nodes(
v=True,
h="id,ip,port,v,m",
)
print(resp)
response = client.cat.nodes( v: true, h: 'id,ip,port,v,m' ) puts response
const response = await client.cat.nodes({
v: "true",
h: "id,ip,port,v,m",
});
console.log(response);
GET /_cat/nodes?v=true&h=id,ip,port,v,m
The API returns the following response:
id ip port v m veJR 127.0.0.1 59938 8.16.0 *