Get index information

Get shard allocation information

GET /_cat/allocation/{node_id}

Get a snapshot of the number of shards allocated to each data node and their disk space.

IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.

Path parameters

node_id string | array[string] Required

A comma-separated list of node identifiers or names used to limit the returned information.

Query parameters

bytes string

The unit used to display byte values.

Values are b, kb, mb, gb, tb, or pb.
local boolean

If true, the request computes the list of selected nodes from the local cluster state. If false the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node.
master_timeout string

Period to wait for a connection to the master node.

Responses

200

application/json

application/json text/plain
Hide response attributes Show response attributes object
- shards string
  
  Number of primary and replica shards assigned to the node.
- shards.undesired string | null
  
  Amount of shards that are scheduled to be moved elsewhere in the cluster or -1 other than desired balance allocator is used
  
  One of:
  string-1 string string-2 string | null
- write_load.forecast number | string | null
  
  Sum of index write load forecasts
  
  One of:
  _spec_utils:Stringifieddouble number _spec_utils:Stringifieddouble string string-2 string | null
- disk.indices.forecast number | string | null
  
  Sum of shard size forecasts
  
  One of:
  _types:ByteSize number _types:ByteSize string string-2 string | null
- disk.indices number | string | null
  
  Disk space used by the node’s shards. Does not include disk space for the translog or unassigned shards. IMPORTANT: This metric double-counts disk space for hard-linked files, such as those created when shrinking, splitting, or cloning an index.
  
  One of:
  _types:ByteSize number _types:ByteSize string string-2 string | null
- disk.used number | string | null
  
  Total disk space in use. Elasticsearch retrieves this metric from the node’s operating system (OS). The metric includes disk space for: Elasticsearch, including the translog and unassigned shards; the node’s operating system; any other applications or files on the node. Unlike disk.indices, this metric does not double-count disk space for hard-linked files.
  
  One of:
  _types:ByteSize number _types:ByteSize string string-2 string | null
- disk.avail number | string | null
  
  Free disk space available to Elasticsearch. Elasticsearch retrieves this metric from the node’s operating system. Disk-based shard allocation uses this metric to assign shards to nodes based on available disk space.
  
  One of:
  _types:ByteSize number _types:ByteSize string string-2 string | null
- disk.total number | string | null
  
  Total disk space for the node, including in-use and available space.
  
  One of:
  _types:ByteSize number _types:ByteSize string string-2 string | null
- disk.percent string | number | null
  
  Total percentage of disk space in use. Calculated as disk.used / disk.total.
  
  One of:
  _types:Percentage string _types:Percentage number string-2 string | null
- host string | null
  
  Network host for the node. Set using the network.host setting.
  
  One of:
  _types:Host string string-2 string | null
- ip string | null
  
  IP address and port for the node.
  
  One of:
  _types:Ip string string-2 string | null
- node string
  
  Name for the node. Set using the node.name setting.
- node.role string | null
  
  Node roles
  
  One of:
  string-1 string string-2 string | null

GET /_cat/allocation/{node_id}

curl \
 --request GET 'http://api.example.com/_cat/allocation/{node_id}' \
 --header "Authorization: $API_KEY"

Response examples (200)

[
  {
    "shards": "string",
    "shards.undesired": "string",
    "": "string",
    "host": "string",
    "ip": "string",
    "node": "string",
    "node.role": "string"
  }
]

Response examples (200)

A successful response from `GET /_cat/allocation?v=true`. It shows a single shard is allocated to the one node available.

shards shards.undesired write_load.forecast disk.indices.forecast disk.indices disk.used disk.avail disk.total disk.percent host      ip        node    node.role
     1                0                 0.0                  260b         260b    47.3gb     43.4gb    100.7gb           46 127.0.0.1 127.0.0.1 CSUXak2 himrst

Get a document count

GET /_cat/count/{index}

Api key auth Basic auth Bearer auth

Get quick access to a document count for a data stream, an index, or an entire cluster. The document count only includes live documents, not deleted documents which have not yet been removed by the merge process.

IMPORTANT: CAT 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 count API.

Path parameters

index string | array[string] Required

A comma-separated list of data streams, indices, and aliases used to limit the request. It supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.

Responses

200

application/json

application/json text/plain
Hide response attributes Show response attributes object
- epoch number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  _types:UnitSeconds number _spec_utils:StringifiedEpochTimeUnitSeconds string
  
  Time unit for seconds
- timestamp string
  
  Time of day, expressed as HH:MM:SS
- count string
  
  the document count

GET /_cat/count/{index}

curl \
 --request GET 'http://api.example.com/_cat/count/{index}' \
 --header "Authorization: $API_KEY"

Response examples (200)

[
  {
    "": 42.0,
    "timestamp": "string",
    "count": "string"
  }
]

Response examples (200)

A successful response from `GET /_cat/count/my-index-000001?v=true`. It retrieves the document count for the `my-index-000001` data stream or index.

epoch      timestamp count
1475868259 15:24:20  120

A successful response from `GET /_cat/count?v=true`. It retrieves the document count for all data streams and indices in the cluster.

epoch      timestamp count
1475868259 15:24:20  121

GET /_cat/indices

Api key auth Basic auth Bearer auth

Get high-level information about indices in a cluster, including backing indices for data streams.

Use this request to get the following information for each index in a cluster:

shard count
document count
deleted document count
primary store size
total store size of all shards, including shard replicas

These metrics are retrieved directly from Lucene, which Elasticsearch uses internally to power indexing and search. As a result, all document counts include hidden nested documents. To get an accurate count of Elasticsearch documents, use the cat count or count APIs.

CAT 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 an index endpoint.

Query parameters

bytes string

The unit used to display byte values.

Values are b, kb, mb, gb, tb, or pb.
expand_wildcards string | array[string]

The type of index that wildcard patterns can match.
health string

The health status used to limit returned indices. By default, the response includes indices of any health status.

Values are green, GREEN, yellow, YELLOW, red, or RED.
include_unloaded_segments boolean

If true, the response includes information from segments that are not loaded into memory.
pri boolean

If true, the response only includes information from primary shards.
time string

The unit used to display time values.

Values are nanos, micros, ms, s, m, h, or d.
master_timeout string

Period to wait for a connection to the master node.

Responses

200

application/json

application/json text/plain
Hide response attributes Show response attributes object
- health string
  
  current health status
- status string
  
  open/close status
- index string
  
  index name
- uuid string
  
  index uuid
- pri string
  
  number of primary shards
- rep string
  
  number of replica shards
- docs.count string | null
  
  available docs
  
  One of:
  string-1 string string-2 string | null
- docs.deleted string | null
  
  deleted docs
  
  One of:
  string-1 string string-2 string | null
- creation.date string
  
  index creation date (millisecond value)
- creation.date.string string
  
  index creation date (as string)
- store.size string | null
  
  store size of primaries & replicas
  
  One of:
  string-1 string string-2 string | null
- pri.store.size string | null
  
  store size of primaries
  
  One of:
  string-1 string string-2 string | null
- dataset.size string | null
  
  total size of dataset (including the cache for partially mounted indices)
  
  One of:
  string-1 string string-2 string | null
- completion.size string
  
  size of completion
- pri.completion.size string
  
  size of completion
- fielddata.memory_size string
  
  used fielddata cache
- pri.fielddata.memory_size string
  
  used fielddata cache
- fielddata.evictions string
  
  fielddata evictions
- pri.fielddata.evictions string
  
  fielddata evictions
- query_cache.memory_size string
  
  used query cache
- pri.query_cache.memory_size string
  
  used query cache
- query_cache.evictions string
  
  query cache evictions
- pri.query_cache.evictions string
  
  query cache evictions
- request_cache.memory_size string
  
  used request cache
- pri.request_cache.memory_size string
  
  used request cache
- request_cache.evictions string
  
  request cache evictions
- pri.request_cache.evictions string
  
  request cache evictions
- request_cache.hit_count string
  
  request cache hit count
- pri.request_cache.hit_count string
  
  request cache hit count
- request_cache.miss_count string
  
  request cache miss count
- pri.request_cache.miss_count string
  
  request cache miss count
- flush.total string
  
  number of flushes
- pri.flush.total string
  
  number of flushes
- flush.total_time string
  
  time spent in flush
- pri.flush.total_time string
  
  time spent in flush
- get.current string
  
  number of current get ops
- pri.get.current string
  
  number of current get ops
- get.time string
  
  time spent in get
- pri.get.time string
  
  time spent in get
- get.total string
  
  number of get ops
- pri.get.total string
  
  number of get ops
- get.exists_time string
  
  time spent in successful gets
- pri.get.exists_time string
  
  time spent in successful gets
- get.exists_total string
  
  number of successful gets
- pri.get.exists_total string
  
  number of successful gets
- get.missing_time string
  
  time spent in failed gets
- pri.get.missing_time string
  
  time spent in failed gets
- get.missing_total string
  
  number of failed gets
- pri.get.missing_total string
  
  number of failed gets
- indexing.delete_current string
  
  number of current deletions
- pri.indexing.delete_current string
  
  number of current deletions
- indexing.delete_time string
  
  time spent in deletions
- pri.indexing.delete_time string
  
  time spent in deletions
- indexing.delete_total string
  
  number of delete ops
- pri.indexing.delete_total string
  
  number of delete ops
- indexing.index_current string
  
  number of current indexing ops
- pri.indexing.index_current string
  
  number of current indexing ops
- indexing.index_time string
  
  time spent in indexing
- pri.indexing.index_time string
  
  time spent in indexing
- indexing.index_total string
  
  number of indexing ops
- pri.indexing.index_total string
  
  number of indexing ops
- indexing.index_failed string
  
  number of failed indexing ops
- pri.indexing.index_failed string
  
  number of failed indexing ops
- merges.current string
  
  number of current merges
- pri.merges.current string
  
  number of current merges
- merges.current_docs string
  
  number of current merging docs
- pri.merges.current_docs string
  
  number of current merging docs
- merges.current_size string
  
  size of current merges
- pri.merges.current_size string
  
  size of current merges
- merges.total string
  
  number of completed merge ops
- pri.merges.total string
  
  number of completed merge ops
- merges.total_docs string
  
  docs merged
- pri.merges.total_docs string
  
  docs merged
- merges.total_size string
  
  size merged
- pri.merges.total_size string
  
  size merged
- merges.total_time string
  
  time spent in merges
- pri.merges.total_time string
  
  time spent in merges
- refresh.total string
  
  total refreshes
- pri.refresh.total string
  
  total refreshes
- refresh.time string
  
  time spent in refreshes
- pri.refresh.time string
  
  time spent in refreshes
- refresh.external_total string
  
  total external refreshes
- pri.refresh.external_total string
  
  total external refreshes
- refresh.external_time string
  
  time spent in external refreshes
- pri.refresh.external_time string
  
  time spent in external refreshes
- refresh.listeners string
  
  number of pending refresh listeners
- pri.refresh.listeners string
  
  number of pending refresh listeners
- search.fetch_current string
  
  current fetch phase ops
- pri.search.fetch_current string
  
  current fetch phase ops
- search.fetch_time string
  
  time spent in fetch phase
- pri.search.fetch_time string
  
  time spent in fetch phase
- search.fetch_total string
  
  total fetch ops
- pri.search.fetch_total string
  
  total fetch ops
- search.open_contexts string
  
  open search contexts
- pri.search.open_contexts string
  
  open search contexts
- search.query_current string
  
  current query phase ops
- pri.search.query_current string
  
  current query phase ops
- search.query_time string
  
  time spent in query phase
- pri.search.query_time string
  
  time spent in query phase
- search.query_total string
  
  total query phase ops
- pri.search.query_total string
  
  total query phase ops
- search.scroll_current string
  
  open scroll contexts
- pri.search.scroll_current string
  
  open scroll contexts
- search.scroll_time string
  
  time scroll contexts held open
- pri.search.scroll_time string
  
  time scroll contexts held open
- search.scroll_total string
  
  completed scroll contexts
- pri.search.scroll_total string
  
  completed scroll contexts
- segments.count string
  
  number of segments
- pri.segments.count string
  
  number of segments
- segments.memory string
  
  memory used by segments
- pri.segments.memory string
  
  memory used by segments
- segments.index_writer_memory string
  
  memory used by index writer
- pri.segments.index_writer_memory string
  
  memory used by index writer
- segments.version_map_memory string
  
  memory used by version map
- pri.segments.version_map_memory string
  
  memory used by version map
- segments.fixed_bitset_memory string
  
  memory used by fixed bit sets for nested object field types and export type filters for types referred in _parent fields
- pri.segments.fixed_bitset_memory string
  
  memory used by fixed bit sets for nested object field types and export type filters for types referred in _parent fields
- warmer.current string
  
  current warmer ops
- pri.warmer.current string
  
  current warmer ops
- warmer.total string
  
  total warmer ops
- pri.warmer.total string
  
  total warmer ops
- warmer.total_time string
  
  time spent in warmers
- pri.warmer.total_time string
  
  time spent in warmers
- suggest.current string
  
  number of current suggest ops
- pri.suggest.current string
  
  number of current suggest ops
- suggest.time string
  
  time spend in suggest
- pri.suggest.time string
  
  time spend in suggest
- suggest.total string
  
  number of suggest ops
- pri.suggest.total string
  
  number of suggest ops
- memory.total string
  
  total used memory
- pri.memory.total string
  
  total user memory
- search.throttled string
  
  indicates if the index is search throttled
- bulk.total_operations string
  
  number of bulk shard ops
- pri.bulk.total_operations string
  
  number of bulk shard ops
- bulk.total_time string
  
  time spend in shard bulk
- pri.bulk.total_time string
  
  time spend in shard bulk
- bulk.total_size_in_bytes string
  
  total size in bytes of shard bulk
- pri.bulk.total_size_in_bytes string
  
  total size in bytes of shard bulk
- bulk.avg_time string
  
  average time spend in shard bulk
- pri.bulk.avg_time string
  
  average time spend in shard bulk
- bulk.avg_size_in_bytes string
  
  average size in bytes of shard bulk
- pri.bulk.avg_size_in_bytes string
  
  average size in bytes of shard bulk

GET /_cat/indices

curl \
 --request GET 'http://api.example.com/_cat/indices' \
 --header "Authorization: $API_KEY"

Response examples (200)

[
  {
    "health": "string",
    "status": "string",
    "index": "string",
    "uuid": "string",
    "pri": "string",
    "rep": "string",
    "docs.count": "string",
    "docs.deleted": "string",
    "creation.date": "string",
    "creation.date.string": "string",
    "store.size": "string",
    "pri.store.size": "string",
    "dataset.size": "string",
    "completion.size": "string",
    "pri.completion.size": "string",
    "fielddata.memory_size": "string",
    "pri.fielddata.memory_size": "string",
    "fielddata.evictions": "string",
    "pri.fielddata.evictions": "string",
    "query_cache.memory_size": "string",
    "pri.query_cache.memory_size": "string",
    "query_cache.evictions": "string",
    "pri.query_cache.evictions": "string",
    "request_cache.memory_size": "string",
    "pri.request_cache.memory_size": "string",
    "request_cache.evictions": "string",
    "pri.request_cache.evictions": "string",
    "request_cache.hit_count": "string",
    "pri.request_cache.hit_count": "string",
    "request_cache.miss_count": "string",
    "pri.request_cache.miss_count": "string",
    "flush.total": "string",
    "pri.flush.total": "string",
    "flush.total_time": "string",
    "pri.flush.total_time": "string",
    "get.current": "string",
    "pri.get.current": "string",
    "get.time": "string",
    "pri.get.time": "string",
    "get.total": "string",
    "pri.get.total": "string",
    "get.exists_time": "string",
    "pri.get.exists_time": "string",
    "get.exists_total": "string",
    "pri.get.exists_total": "string",
    "get.missing_time": "string",
    "pri.get.missing_time": "string",
    "get.missing_total": "string",
    "pri.get.missing_total": "string",
    "indexing.delete_current": "string",
    "pri.indexing.delete_current": "string",
    "indexing.delete_time": "string",
    "pri.indexing.delete_time": "string",
    "indexing.delete_total": "string",
    "pri.indexing.delete_total": "string",
    "indexing.index_current": "string",
    "pri.indexing.index_current": "string",
    "indexing.index_time": "string",
    "pri.indexing.index_time": "string",
    "indexing.index_total": "string",
    "pri.indexing.index_total": "string",
    "indexing.index_failed": "string",
    "pri.indexing.index_failed": "string",
    "merges.current": "string",
    "pri.merges.current": "string",
    "merges.current_docs": "string",
    "pri.merges.current_docs": "string",
    "merges.current_size": "string",
    "pri.merges.current_size": "string",
    "merges.total": "string",
    "pri.merges.total": "string",
    "merges.total_docs": "string",
    "pri.merges.total_docs": "string",
    "merges.total_size": "string",
    "pri.merges.total_size": "string",
    "merges.total_time": "string",
    "pri.merges.total_time": "string",
    "refresh.total": "string",
    "pri.refresh.total": "string",
    "refresh.time": "string",
    "pri.refresh.time": "string",
    "refresh.external_total": "string",
    "pri.refresh.external_total": "string",
    "refresh.external_time": "string",
    "pri.refresh.external_time": "string",
    "refresh.listeners": "string",
    "pri.refresh.listeners": "string",
    "search.fetch_current": "string",
    "pri.search.fetch_current": "string",
    "search.fetch_time": "string",
    "pri.search.fetch_time": "string",
    "search.fetch_total": "string",
    "pri.search.fetch_total": "string",
    "search.open_contexts": "string",
    "pri.search.open_contexts": "string",
    "search.query_current": "string",
    "pri.search.query_current": "string",
    "search.query_time": "string",
    "pri.search.query_time": "string",
    "search.query_total": "string",
    "pri.search.query_total": "string",
    "search.scroll_current": "string",
    "pri.search.scroll_current": "string",
    "search.scroll_time": "string",
    "pri.search.scroll_time": "string",
    "search.scroll_total": "string",
    "pri.search.scroll_total": "string",
    "segments.count": "string",
    "pri.segments.count": "string",
    "segments.memory": "string",
    "pri.segments.memory": "string",
    "segments.index_writer_memory": "string",
    "pri.segments.index_writer_memory": "string",
    "segments.version_map_memory": "string",
    "pri.segments.version_map_memory": "string",
    "segments.fixed_bitset_memory": "string",
    "pri.segments.fixed_bitset_memory": "string",
    "warmer.current": "string",
    "pri.warmer.current": "string",
    "warmer.total": "string",
    "pri.warmer.total": "string",
    "warmer.total_time": "string",
    "pri.warmer.total_time": "string",
    "suggest.current": "string",
    "pri.suggest.current": "string",
    "suggest.time": "string",
    "pri.suggest.time": "string",
    "suggest.total": "string",
    "pri.suggest.total": "string",
    "memory.total": "string",
    "pri.memory.total": "string",
    "search.throttled": "string",
    "bulk.total_operations": "string",
    "pri.bulk.total_operations": "string",
    "bulk.total_time": "string",
    "pri.bulk.total_time": "string",
    "bulk.total_size_in_bytes": "string",
    "pri.bulk.total_size_in_bytes": "string",
    "bulk.avg_time": "string",
    "pri.bulk.avg_time": "string",
    "bulk.avg_size_in_bytes": "string",
    "pri.bulk.avg_size_in_bytes": "string"
  }
]

Response examples (200)

A successful response from `GET /_cat/indices/my-index-*?v=true&s=index`.

health status index            uuid                   pri rep docs.count docs.deleted store.size pri.store.size dataset.size
yellow open   my-index-000001  u8FNjxh8Rfy_awN11oDKYQ   1   1       1200            0     88.1kb         88.1kb       88.1kb
green  open   my-index-000002  nYFWZEO7TUiOjLQXBaYJpA   1   0          0            0       260b           260b         260b

shards.undesired string | null

write_load.forecast number | string | null

disk.indices.forecast number | string | null

disk.indices number | string | null

disk.used number | string | null

disk.avail number | string | null

disk.total number | string | null

disk.percent string | number | null

host string | null

ip string | null

node.role string | null

epoch number | string

docs.count string | null

docs.deleted string | null

store.size string | null

pri.store.size string | null

dataset.size string | null