Get an autoscaling policy Added in 7.11.0

GET /_autoscaling/policy/{name}

NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.

Path parameters

  • name string Required

    the name of the autoscaling policy

Query parameters

  • Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
GET /_autoscaling/policy/{name}
curl \
 --request GET http://api.example.com/_autoscaling/policy/{name}
Response examples (200)
This may be a response to `GET /_autoscaling/policy/my_autoscaling_policy`.
{
   "roles": <roles>,
   "deciders": <deciders>
}

Create or update an autoscaling policy Added in 7.11.0

PUT /_autoscaling/policy/{name}

NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.

Path parameters

  • name string Required

    the name of the autoscaling policy

Query parameters

  • Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • timeout string

    Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

application/json

Body Required

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • acknowledged boolean Required

      For a successful response, this value is always true. On failure, an exception is returned instead.

PUT /_autoscaling/policy/{name}
curl \
 --request PUT http://api.example.com/_autoscaling/policy/{name} \
 --header "Content-Type: application/json" \
 --data '"{\n  \"roles\": [],\n  \"deciders\": {\n    \"fixed\": {\n    }\n  }\n}"'
Request examples
{
  "roles": [],
  "deciders": {
    "fixed": {
    }
  }
}
The API method and path for this request: `PUT /_autoscaling/policy/my_autoscaling_policy`. It creates `my_autoscaling_policy` using the fixed autoscaling decider, applying to the set of nodes having (only) the `data_hot` role.
{
  "roles" : [ "data_hot" ],
  "deciders": {
    "fixed": {
    }
  }
}
Response examples (200)
{
  "acknowledged": true
}




Get the autoscaling capacity Added in 7.11.0

GET /_autoscaling/capacity

NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.

This API gets the current autoscaling capacity based on the configured autoscaling policy. It will return information to size the cluster appropriately to the current workload.

The required_capacity is calculated as the maximum of the required_capacity result of all individual deciders that are enabled for the policy.

The operator should verify that the current_nodes match the operator’s knowledge of the cluster to avoid making autoscaling decisions based on stale or incomplete information.

The response contains decider-specific information you can use to diagnose how and why autoscaling determined a certain capacity was required. This information is provided for diagnosis only. Do not use this information to make autoscaling decisions.

Query parameters

  • Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • policies object Required
      Hide policies attribute Show policies attribute object
      • * object Additional properties

        Additional properties are allowed.

        Hide * attributes Show * attributes object
        • required_capacity object Required

          Additional properties are allowed.

          Hide required_capacity attributes Show required_capacity attributes object
          • node object Required

            Additional properties are allowed.

            Hide node attributes Show node attributes object
          • total object Required

            Additional properties are allowed.

            Hide total attributes Show total attributes object
        • current_capacity object Required

          Additional properties are allowed.

          Hide current_capacity attributes Show current_capacity attributes object
          • node object Required

            Additional properties are allowed.

            Hide node attributes Show node attributes object
          • total object Required

            Additional properties are allowed.

            Hide total attributes Show total attributes object
        • current_nodes array[object] Required
          Hide current_nodes attribute Show current_nodes attribute object
        • deciders object Required
          Hide deciders attribute Show deciders attribute object
          • * object Additional properties

            Additional properties are allowed.

            Hide * attributes Show * attributes object
            • required_capacity object Required

              Additional properties are allowed.

              Hide required_capacity attributes Show required_capacity attributes object
              • node object Required

                Additional properties are allowed.

              • total object Required

                Additional properties are allowed.

            • Additional properties are allowed.

GET /_autoscaling/capacity
curl \
 --request GET http://api.example.com/_autoscaling/capacity
Response examples (200)
This may be a response to `GET /_autoscaling/capacity`.
{
  policies: {}
}

Get behavioral analytics collections Technical preview

GET /_application/analytics/{name}

Path parameters

  • name array[string] Required

    A list of analytics collections to limit the returned information

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • * object Additional properties

      Additional properties are allowed.

      Hide * attribute Show * attribute object
      • event_data_stream object Required

        Additional properties are allowed.

        Hide event_data_stream attribute Show event_data_stream attribute object
GET /_application/analytics/{name}
curl \
 --request GET http://api.example.com/_application/analytics/{name}
Response examples (200)
A successful response from `GET _application/analytics/my*`
{
  "my_analytics_collection": {
      "event_data_stream": {
          "name": "behavioral_analytics-events-my_analytics_collection"
      }
  },
  "my_analytics_collection2": {
      "event_data_stream": {
          "name": "behavioral_analytics-events-my_analytics_collection2"
      }
  }
}




Delete a behavioral analytics collection Technical preview

DELETE /_application/analytics/{name}

The associated data stream is also deleted.

Path parameters

  • name string Required

    The name of the analytics collection to be deleted

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • acknowledged boolean Required

      For a successful response, this value is always true. On failure, an exception is returned instead.

DELETE /_application/analytics/{name}
curl \
 --request DELETE http://api.example.com/_application/analytics/{name}
Response examples (200)
{
  "acknowledged": true
}

Get behavioral analytics collections Technical preview

GET /_application/analytics

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • * object Additional properties

      Additional properties are allowed.

      Hide * attribute Show * attribute object
      • event_data_stream object Required

        Additional properties are allowed.

        Hide event_data_stream attribute Show event_data_stream attribute object
GET /_application/analytics
curl \
 --request GET http://api.example.com/_application/analytics
Response examples (200)
A successful response from `GET _application/analytics/my*`
{
  "my_analytics_collection": {
      "event_data_stream": {
          "name": "behavioral_analytics-events-my_analytics_collection"
      }
  },
  "my_analytics_collection2": {
      "event_data_stream": {
          "name": "behavioral_analytics-events-my_analytics_collection2"
      }
  }
}





Get aliases

GET /_cat/aliases

Get the cluster's index aliases, including filter and routing information. This API does not return data stream aliases.

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

Query parameters

  • expand_wildcards string | array[string]

    The type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. It supports comma-separated values, such as open,hidden.

  • The period to wait for a connection to the master node. If the master node is not available before the timeout expires, the request fails and returns an error. To indicated that the request should never timeout, you can set it to -1.

Responses

GET /_cat/aliases
curl \
 --request GET http://api.example.com/_cat/aliases
Response examples (200)
[
  {
    "alias": "string",
    "index": "string",
    "filter": "string",
    "routing.index": "string",
    "routing.search": "string",
    "is_write_index": "string"
  }
]




Get shard allocation information

GET /_cat/allocation

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.

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.

  • Period to wait for a connection to the master node.

Responses

GET /_cat/allocation
curl \
 --request GET http://api.example.com/_cat/allocation
Response examples (200)
[
  {
    "shards": "string",
    "shards.undesired": "string",
    "": "string",
    "host": "string",
    "ip": "string",
    "node": "string",
    "node.role": "string"
  }
]
















Get a document count

GET /_cat/count/{index}

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

GET /_cat/count/{index}
curl \
 --request GET http://api.example.com/_cat/count/{index}
Response examples (200)
[
  {
    "": 42.0,
    "timestamp": "string",
    "count": "string"
  }
]

Get field data cache information

GET /_cat/fielddata

Get the amount of heap memory currently used by the field data cache on every data node in the cluster.

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 nodes stats API.

Query parameters

  • bytes string

    The unit used to display byte values.

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

  • fields string | array[string]

    Comma-separated list of fields used to limit returned information.

Responses

GET /_cat/fielddata
curl \
 --request GET http://api.example.com/_cat/fielddata
Response examples (200)
[
  {
    "id": "string",
    "host": "string",
    "ip": "string",
    "node": "string",
    "field": "string",
    "size": "string"
  }
]








Get CAT help

GET /_cat

Get help for the CAT APIs.

Responses

  • 200 application/json

    Additional properties are allowed.

GET /_cat
curl \
 --request GET http://api.example.com/_cat
Response examples (200)
{}

Get index information

GET /_cat/indices

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.

  • 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.

  • Period to wait for a connection to the master node.

Responses

GET /_cat/indices
curl \
 --request GET http://api.example.com/_cat/indices
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"
  }
]












Get data frame analytics jobs Added in 7.7.0

GET /_cat/ml/data_frame/analytics/{id}

Get configuration and usage information about data frame analytics jobs.

IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get data frame analytics jobs statistics API.

Path parameters

  • id string Required

    The ID of the data frame analytics to fetch

Query parameters

  • Whether to ignore if a wildcard expression matches no configs. (This includes _all string or when no configs have been specified)

  • bytes string

    The unit in which to display byte values

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

  • h string | array[string]

    Comma-separated list of column names to display.

  • s string | array[string]

    Comma-separated list of column names or column aliases used to sort the response.

  • time string

    Unit used to display time values.

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

Responses

GET /_cat/ml/data_frame/analytics/{id}
curl \
 --request GET http://api.example.com/_cat/ml/data_frame/analytics/{id}
Response examples (200)
[
  {
    "id": "string",
    "type": "string",
    "create_time": "string",
    "version": "string",
    "source_index": "string",
    "dest_index": "string",
    "description": "string",
    "model_memory_limit": "string",
    "state": "string",
    "failure_reason": "string",
    "progress": "string",
    "assignment_explanation": "string",
    "node.id": "string",
    "node.name": "string",
    "node.ephemeral_id": "string",
    "node.address": "string"
  }
]
















Get trained models Added in 7.7.0

GET /_cat/ml/trained_models

Get configuration and usage information about inference trained models.

IMPORTANT: CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get trained models statistics API.

Query parameters

  • Specifies what to do when the request: contains wildcard expressions and there are no models that match; contains the _all string or no identifiers and there are no matches; contains wildcard expressions and there are only partial matches. If true, the API returns an empty array when there are no matches and the subset of results when there are partial matches. If false, the API returns a 404 status code when there are no matches or only partial matches.

  • bytes string

    The unit used to display byte values.

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

  • h string | array[string]

    A comma-separated list of column names to display.

  • s string | array[string]

    A comma-separated list of column names or aliases used to sort the response.

  • from number

    Skips the specified number of transforms.

  • size number

    The maximum number of transforms to display.

  • time string

    Unit used to display time values.

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

Responses

GET /_cat/ml/trained_models
curl \
 --request GET http://api.example.com/_cat/ml/trained_models
Response examples (200)
[
  {
    "id": "string",
    "created_by": "string",
    "": "string",
    "operations": "string",
    "license": "string",
    "version": "string",
    "description": "string",
    "ingest.pipelines": "string",
    "ingest.count": "string",
    "ingest.time": "string",
    "ingest.current": "string",
    "ingest.failed": "string",
    "data_frame.id": "string",
    "data_frame.create_time": "string",
    "data_frame.source_index": "string",
    "data_frame.analysis": "string",
    "type": "string"
  }
]




Get node attribute information

GET /_cat/nodeattrs

Get information about custom node attributes. 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 nodes info API.

Query parameters

  • 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.

  • Period to wait for a connection to the master node.

Responses

GET /_cat/nodeattrs
curl \
 --request GET http://api.example.com/_cat/nodeattrs
Response examples (200)
[
  {
    "node": "string",
    "id": "string",
    "pid": "string",
    "host": "string",
    "ip": "string",
    "port": "string",
    "attr": "string",
    "value": "string"
  }
]
















Get shard recovery information

GET /_cat/recovery/{index}

Get information about ongoing and completed shard recoveries. Shard recovery is the process of initializing a shard copy, such as restoring a primary shard from a snapshot or syncing a replica shard from a primary shard. When a shard recovery completes, the recovered shard is available for search and indexing. For data streams, the API returns information about the stream’s backing indices. 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 index recovery API.

Path parameters

  • index string | array[string] Required

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

Query parameters

  • If true, the response only includes ongoing shard recoveries.

  • bytes string

    The unit used to display byte values.

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

  • detailed boolean

    If true, the response includes detailed information about shard recoveries.

  • time string

    Unit used to display time values.

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

Responses

GET /_cat/recovery/{index}
curl \
 --request GET http://api.example.com/_cat/recovery/{index}
Response examples (200)
[
  {
    "index": "string",
    "shard": "string",
    "": "string",
    "time": "string",
    "type": "string",
    "stage": "string",
    "source_host": "string",
    "source_node": "string",
    "target_host": "string",
    "target_node": "string",
    "repository": "string",
    "snapshot": "string",
    "files": "string",
    "files_recovered": "string",
    "files_total": "string",
    "bytes": "string",
    "bytes_recovered": "string",
    "bytes_total": "string",
    "translog_ops": "string",
    "translog_ops_recovered": "string"
  }
]
















Get shard information

GET /_cat/shards/{index}

Get information about the shards in a cluster. For data streams, the API returns information about the backing indices. 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

  • index string | array[string] Required

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

Query parameters

  • bytes string

    The unit used to display byte values.

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

  • Period to wait for a connection to the master node.

  • time string

    Unit used to display time values.

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

Responses

GET /_cat/shards/{index}
curl \
 --request GET http://api.example.com/_cat/shards/{index}
Response examples (200)
[
  {
    "index": "string",
    "shard": "string",
    "prirep": "string",
    "state": "string",
    "docs": "string",
    "store": "string",
    "dataset": "string",
    "ip": "string",
    "id": "string",
    "node": "string",
    "sync_id": "string",
    "unassigned.reason": "string",
    "unassigned.at": "string",
    "unassigned.for": "string",
    "unassigned.details": "string",
    "recoverysource.type": "string",
    "completion.size": "string",
    "fielddata.memory_size": "string",
    "fielddata.evictions": "string",
    "query_cache.memory_size": "string",
    "query_cache.evictions": "string",
    "flush.total": "string",
    "flush.total_time": "string",
    "get.current": "string",
    "get.time": "string",
    "get.total": "string",
    "get.exists_time": "string",
    "get.exists_total": "string",
    "get.missing_time": "string",
    "get.missing_total": "string",
    "indexing.delete_current": "string",
    "indexing.delete_time": "string",
    "indexing.delete_total": "string",
    "indexing.index_current": "string",
    "indexing.index_time": "string",
    "indexing.index_total": "string",
    "indexing.index_failed": "string",
    "merges.current": "string",
    "merges.current_docs": "string",
    "merges.current_size": "string",
    "merges.total": "string",
    "merges.total_docs": "string",
    "merges.total_size": "string",
    "merges.total_time": "string",
    "refresh.total": "string",
    "refresh.time": "string",
    "refresh.external_total": "string",
    "refresh.external_time": "string",
    "refresh.listeners": "string",
    "search.fetch_current": "string",
    "search.fetch_time": "string",
    "search.fetch_total": "string",
    "search.open_contexts": "string",
    "search.query_current": "string",
    "search.query_time": "string",
    "search.query_total": "string",
    "search.scroll_current": "string",
    "search.scroll_time": "string",
    "search.scroll_total": "string",
    "segments.count": "string",
    "segments.memory": "string",
    "segments.index_writer_memory": "string",
    "segments.version_map_memory": "string",
    "segments.fixed_bitset_memory": "string",
    "seq_no.max": "string",
    "seq_no.local_checkpoint": "string",
    "seq_no.global_checkpoint": "string",
    "warmer.current": "string",
    "warmer.total": "string",
    "warmer.total_time": "string",
    "path.data": "string",
    "path.state": "string",
    "bulk.total_operations": "string",
    "bulk.total_time": "string",
    "bulk.total_size_in_bytes": "string",
    "bulk.avg_time": "string",
    "bulk.avg_size_in_bytes": "string"
  }
]

Get snapshot information Added in 2.1.0

GET /_cat/snapshots

Get information about the snapshots stored in one or more repositories. A snapshot is a backup of an index or running Elasticsearch cluster. 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 get snapshot API.

Query parameters

  • If true, the response does not include information from unavailable snapshots.

  • Period to wait for a connection to the master node.

  • time string

    Unit used to display time values.

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

Responses

  • Hide response attributes Show response attributes object
    • id string

      The unique identifier for the snapshot.

    • The repository name.

    • status string

      The state of the snapshot process. Returned values include: FAILED: The snapshot process failed. INCOMPATIBLE: The snapshot process is incompatible with the current cluster version. IN_PROGRESS: The snapshot process started but has not completed. PARTIAL: The snapshot process completed with a partial success. SUCCESS: The snapshot process completed with a full success.

    • start_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.

    • start_time string | object

      A time of day, expressed either as hh:mm, noon, midnight, or an hour/minutes structure.

      One of:
    • end_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.

    • end_time string

      Time of day, expressed as HH:MM:SS

    • duration string

      A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

    • indices string

      The number of indices in the snapshot.

    • The number of successful shards in the snapshot.

    • The number of failed shards in the snapshot.

    • The total number of shards in the snapshot.

    • reason string

      The reason for any snapshot failures.

GET /_cat/snapshots
curl \
 --request GET http://api.example.com/_cat/snapshots
Response examples (200)
[
  {
    "id": "string",
    "repository": "string",
    "status": "string",
    "": 42.0,
    "end_time": "string",
    "duration": "string",
    "indices": "string",
    "successful_shards": "string",
    "failed_shards": "string",
    "total_shards": "string",
    "reason": "string"
  }
]

Get snapshot information Added in 2.1.0

GET /_cat/snapshots/{repository}

Get information about the snapshots stored in one or more repositories. A snapshot is a backup of an index or running Elasticsearch cluster. 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 get snapshot API.

Path parameters

  • repository string | array[string] Required

    A comma-separated list of snapshot repositories used to limit the request. Accepts wildcard expressions. _all returns all repositories. If any repository fails during the request, Elasticsearch returns an error.

Query parameters

  • If true, the response does not include information from unavailable snapshots.

  • Period to wait for a connection to the master node.

  • time string

    Unit used to display time values.

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

Responses

  • Hide response attributes Show response attributes object
    • id string

      The unique identifier for the snapshot.

    • The repository name.

    • status string

      The state of the snapshot process. Returned values include: FAILED: The snapshot process failed. INCOMPATIBLE: The snapshot process is incompatible with the current cluster version. IN_PROGRESS: The snapshot process started but has not completed. PARTIAL: The snapshot process completed with a partial success. SUCCESS: The snapshot process completed with a full success.

    • start_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.

    • start_time string | object

      A time of day, expressed either as hh:mm, noon, midnight, or an hour/minutes structure.

      One of:
    • end_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.

    • end_time string

      Time of day, expressed as HH:MM:SS

    • duration string

      A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

    • indices string

      The number of indices in the snapshot.

    • The number of successful shards in the snapshot.

    • The number of failed shards in the snapshot.

    • The total number of shards in the snapshot.

    • reason string

      The reason for any snapshot failures.

GET /_cat/snapshots/{repository}
curl \
 --request GET http://api.example.com/_cat/snapshots/{repository}
Response examples (200)
[
  {
    "id": "string",
    "repository": "string",
    "status": "string",
    "": 42.0,
    "end_time": "string",
    "duration": "string",
    "indices": "string",
    "successful_shards": "string",
    "failed_shards": "string",
    "total_shards": "string",
    "reason": "string"
  }
]








Get index template information Added in 5.2.0

GET /_cat/templates/{name}

Get information about the index templates in a cluster. You can use index templates to apply index settings and field mappings to new indices at creation. 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 get index template API.

Path parameters

  • name string Required

    The name of the template to return. Accepts wildcard expressions. If omitted, all templates are returned.

Query parameters

  • 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.

  • Period to wait for a connection to the master node.

Responses

GET /_cat/templates/{name}
curl \
 --request GET http://api.example.com/_cat/templates/{name}
Response examples (200)
[
  {
    "name": "string",
    "index_patterns": "string",
    "order": "string",
    "version": "string",
    "composed_of": "string"
  }
]




Get thread pool statistics

GET /_cat/thread_pool/{thread_pool_patterns}

Get thread pool statistics for each node in a cluster. Returned information includes all built-in thread pools and custom thread pools. 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 nodes info API.

Path parameters

  • thread_pool_patterns string | array[string] Required

    A comma-separated list of thread pool names used to limit the request. Accepts wildcard expressions.

Query parameters

  • time string

    The unit used to display time values.

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

  • 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.

  • Period to wait for a connection to the master node.

Responses

GET /_cat/thread_pool/{thread_pool_patterns}
curl \
 --request GET http://api.example.com/_cat/thread_pool/{thread_pool_patterns}
Response examples (200)
[
  {
    "node_name": "string",
    "node_id": "string",
    "ephemeral_node_id": "string",
    "pid": "string",
    "host": "string",
    "ip": "string",
    "port": "string",
    "name": "string",
    "type": "string",
    "active": "string",
    "pool_size": "string",
    "queue": "string",
    "queue_size": "string",
    "rejected": "string",
    "largest": "string",
    "completed": "string",
    "core": "string",
    "max": "string",
    "size": "string",
    "keep_alive": "string"
  }
]

Get transform information Added in 7.7.0

GET /_cat/transforms

Get configuration and usage information about transforms.

CAT APIs are only intended for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, use the get transform statistics API.

Query parameters

  • Specifies what to do when the request: contains wildcard expressions and there are no transforms that match; contains the _all string or no identifiers and there are no matches; contains wildcard expressions and there are only partial matches. If true, it returns an empty transforms array when there are no matches and the subset of results when there are partial matches. If false, the request returns a 404 status code when there are no matches or only partial matches.

  • from number

    Skips the specified number of transforms.

  • h string | array[string]

    Comma-separated list of column names to display.

  • s string | array[string]

    Comma-separated list of column names or column aliases used to sort the response.

  • time string

    The unit used to display time values.

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

  • size number

    The maximum number of transforms to obtain.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • id string
    • state string

      The status of the transform. Returned values include: aborting: The transform is aborting. failed: The transform failed. For more information about the failure, check thereasonfield. indexing: The transform is actively processing data and creating new documents. started: The transform is running but not actively indexing data. stopped: The transform is stopped. stopping`: The transform is stopping.

    • The sequence number for the checkpoint.

    • The number of documents that have been processed from the source index of the transform.

    • checkpoint_progress string | null

      The progress of the next checkpoint that is currently in progress.

    • last_search_time string | null

      The timestamp of the last search in the source indices. This field is shown only if the transform is running.

    • changes_last_detection_time string | null

      The timestamp when changes were last detected in the source indices.

    • The time the transform was created.

    • version string
    • The source indices for the transform.

    • The destination index for the transform.

    • pipeline string

      The unique identifier for the ingest pipeline.

    • The description of the transform.

    • The type of transform: batch or continuous.

    • The interval between checks for changes in the source indices when the transform is running continuously.

    • The initial page size that is used for the composite aggregation for each checkpoint.

    • The number of input documents per second.

    • reason string

      If a transform has a failed state, these details describe the reason for failure.

    • The total number of search operations on the source index for the transform.

    • The total number of search failures.

    • The total amount of search time, in milliseconds.

    • The total number of index operations done by the transform.

    • The total number of indexing failures.

    • The total time spent indexing documents, in milliseconds.

    • The number of documents that have been indexed into the destination index for the transform.

    • The total time spent deleting documents, in milliseconds.

    • The number of documents deleted from the destination index due to the retention policy for the transform.

    • The number of times the transform has been triggered by the scheduler. For example, the scheduler triggers the transform indexer to check for updates or ingest new data at an interval specified in the frequency property.

    • The number of search or bulk index operations processed. Documents are processed in batches instead of individually.

    • The total time spent processing results, in milliseconds.

    • The exponential moving average of the duration of the checkpoint, in milliseconds.

    • The exponential moving average of the number of new documents that have been indexed.

    • The exponential moving average of the number of documents that have been processed.

GET /_cat/transforms
curl \
 --request GET http://api.example.com/_cat/transforms
Response examples (200)
A successful response from `GET /_cat/transforms?v=true&format=json`.
[
  {
    "id" : "ecommerce_transform",
    "state" : "started",
    "checkpoint" : "1",
    "documents_processed" : "705",
    "checkpoint_progress" : "100.00",
    "changes_last_detection_time" : null
  }
]
















Clear cluster voting config exclusions Added in 7.0.0

DELETE /_cluster/voting_config_exclusions

Remove master-eligible nodes from the voting configuration exclusion list.

Query parameters

  • Period to wait for a connection to the master node.

  • Specifies whether to wait for all excluded nodes to be removed from the cluster before clearing the voting configuration exclusions list. Defaults to true, meaning that all excluded nodes must be removed from the cluster before this API takes any action. If set to false then the voting configuration exclusions list is cleared even if some excluded nodes are still in the cluster.

Responses

DELETE /_cluster/voting_config_exclusions
curl \
 --request DELETE http://api.example.com/_cluster/voting_config_exclusions




Update the cluster settings

PUT /_cluster/settings

Configure and update dynamic settings on a running cluster. You can also configure dynamic settings locally on an unstarted or shut down node in elasticsearch.yml.

Updates made with this API can be persistent, which apply across cluster restarts, or transient, which reset after a cluster restart. You can also reset transient or persistent settings by assigning them a null value.

If you configure the same setting using multiple methods, Elasticsearch applies the settings in following order of precedence: 1) Transient setting; 2) Persistent setting; 3) elasticsearch.yml setting; 4) Default setting value. For example, you can apply a transient setting to override a persistent setting or elasticsearch.yml setting. However, a change to an elasticsearch.yml setting will not override a defined transient or persistent setting.

TIP: In Elastic Cloud, use the user settings feature to configure all cluster settings. This method automatically rejects unsafe settings that could break your cluster. If you run Elasticsearch on your own hardware, use this API to configure dynamic cluster settings. Only use elasticsearch.yml for static cluster settings and node settings. The API doesn’t require a restart and ensures a setting’s value is the same on all nodes.

WARNING: Transient cluster settings are no longer recommended. Use persistent cluster settings instead. If a cluster becomes unstable, transient settings can clear unexpectedly, resulting in a potentially undesired cluster configuration.

Query parameters

application/json

Body Required

  • Hide persistent attribute Show persistent attribute object
    • * object Additional properties

      Additional properties are allowed.

  • Hide transient attribute Show transient attribute object
    • * object Additional properties

      Additional properties are allowed.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • acknowledged boolean Required
    • persistent object Required
      Hide persistent attribute Show persistent attribute object
      • * object Additional properties

        Additional properties are allowed.

    • transient object Required
      Hide transient attribute Show transient attribute object
      • * object Additional properties

        Additional properties are allowed.

PUT /_cluster/settings
curl \
 --request PUT http://api.example.com/_cluster/settings \
 --header "Content-Type: application/json" \
 --data '"{\n  \"persistent\" : {\n    \"indices.recovery.max_bytes_per_sec\" : \"50mb\"\n  }\n}"'
An example of a persistent update.
{
  "persistent" : {
    "indices.recovery.max_bytes_per_sec" : "50mb"
  }
}
PUT `/_cluster/settings` to update the `action.auto_create_index` setting. The setting accepts a comma-separated list of patterns that you want to allow or you can prefix each pattern with `+` or `-` to indicate whether it should be allowed or blocked. In this example, the auto-creation of indices called `my-index-000001` or `index10` is allowed, the creation of indices that match the pattern `index1*` is blocked, and the creation of any other indices that match the `ind*` pattern is allowed. Patterns are matched in the order specified.
{
  "persistent": {
    "action.auto_create_index": "my-index-000001,index10,-index1*,+ind*" 
  }
}
Response examples (200)
{
  "acknowledged": true,
  "persistent": {
    "additionalProperty1": {},
    "additionalProperty2": {}
  },
  "transient": {
    "additionalProperty1": {},
    "additionalProperty2": {}
  }
}

Get the cluster health status Added in 1.3.0

GET /_cluster/health

You can also use the API to get the health status of only specified data streams and indices. For data streams, the API retrieves the health status of the stream’s backing indices.

The cluster health status is: green, yellow or red. On the shard level, a red status indicates that the specific shard is not allocated in the cluster. Yellow means that the primary shard is allocated but replicas are not. Green means that all shards are allocated. The index level status is controlled by the worst shard status.

One of the main benefits of the API is the ability to wait until the cluster reaches a certain high watermark health level. The cluster status is controlled by the worst index status.

Query parameters

  • expand_wildcards string | array[string]

    Whether to expand wildcard expression to concrete indices that are open, closed or both.

  • level string

    Can be one of cluster, indices or shards. Controls the details level of the health information returned.

    Values are cluster, indices, or shards.

  • local boolean

    If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.

  • Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • timeout string

    Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

  • wait_for_active_shards number | string

    A number controlling to how many active shards to wait for, all to wait for all shards in the cluster to be active, or 0 to not wait.

  • Can be one of immediate, urgent, high, normal, low, languid. Wait until all currently queued events with the given priority are processed.

    Values are immediate, urgent, high, normal, low, or languid.

  • wait_for_nodes string | number

    The request waits until the specified number N of nodes is available. It also accepts >=N, <=N, >N and <N. Alternatively, it is possible to use ge(N), le(N), gt(N) and lt(N) notation.

  • A boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard initializations. Defaults to false, which means it will not wait for initializing shards.

  • A boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard relocations. Defaults to false, which means it will not wait for relocating shards.

  • One of green, yellow or red. Will wait (until the timeout provided) until the status of the cluster changes to the one provided or better, i.e. green > yellow > red. By default, will not wait for any status.

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

Responses

GET /_cluster/health
curl \
 --request GET http://api.example.com/_cluster/health
Response examples (200)
A successful response from `GET _cluster/health`. It is the health status of a quiet single node cluster with a single index with one shard and one replica.
{
  "cluster_name" : "testcluster",
  "status" : "yellow",
  "timed_out" : false,
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "active_primary_shards" : 1,
  "active_shards" : 1,
  "relocating_shards" : 0,
  "initializing_shards" : 0,
  "unassigned_shards" : 1,
  "delayed_unassigned_shards": 0,
  "number_of_pending_tasks" : 0,
  "number_of_in_flight_fetch": 0,
  "task_max_waiting_in_queue_millis": 0,
  "active_shards_percent_as_number": 50.0
}

Get the cluster health status Added in 1.3.0

GET /_cluster/health/{index}

You can also use the API to get the health status of only specified data streams and indices. For data streams, the API retrieves the health status of the stream’s backing indices.

The cluster health status is: green, yellow or red. On the shard level, a red status indicates that the specific shard is not allocated in the cluster. Yellow means that the primary shard is allocated but replicas are not. Green means that all shards are allocated. The index level status is controlled by the worst shard status.

One of the main benefits of the API is the ability to wait until the cluster reaches a certain high watermark health level. The cluster status is controlled by the worst index status.

Path parameters

  • index string | array[string] Required

    Comma-separated list of data streams, indices, and index aliases used to limit the request. Wildcard expressions (*) are supported. To target all data streams and indices in a cluster, omit this parameter or use _all or *.

Query parameters

  • expand_wildcards string | array[string]

    Whether to expand wildcard expression to concrete indices that are open, closed or both.

  • level string

    Can be one of cluster, indices or shards. Controls the details level of the health information returned.

    Values are cluster, indices, or shards.

  • local boolean

    If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.

  • Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

  • timeout string

    Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

  • wait_for_active_shards number | string

    A number controlling to how many active shards to wait for, all to wait for all shards in the cluster to be active, or 0 to not wait.

  • Can be one of immediate, urgent, high, normal, low, languid. Wait until all currently queued events with the given priority are processed.

    Values are immediate, urgent, high, normal, low, or languid.

  • wait_for_nodes string | number

    The request waits until the specified number N of nodes is available. It also accepts >=N, <=N, >N and <N. Alternatively, it is possible to use ge(N), le(N), gt(N) and lt(N) notation.

  • A boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard initializations. Defaults to false, which means it will not wait for initializing shards.

  • A boolean value which controls whether to wait (until the timeout provided) for the cluster to have no shard relocations. Defaults to false, which means it will not wait for relocating shards.

  • One of green, yellow or red. Will wait (until the timeout provided) until the status of the cluster changes to the one provided or better, i.e. green > yellow > red. By default, will not wait for any status.

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

Responses

GET /_cluster/health/{index}
curl \
 --request GET http://api.example.com/_cluster/health/{index}
Response examples (200)
A successful response from `GET _cluster/health`. It is the health status of a quiet single node cluster with a single index with one shard and one replica.
{
  "cluster_name" : "testcluster",
  "status" : "yellow",
  "timed_out" : false,
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "active_primary_shards" : 1,
  "active_shards" : 1,
  "relocating_shards" : 0,
  "initializing_shards" : 0,
  "unassigned_shards" : 1,
  "delayed_unassigned_shards": 0,
  "number_of_pending_tasks" : 0,
  "number_of_in_flight_fetch": 0,
  "task_max_waiting_in_queue_millis": 0,
  "active_shards_percent_as_number": 50.0
}




Get the pending cluster tasks

GET /_cluster/pending_tasks

Get information about cluster-level changes (such as create index, update mapping, allocate or fail shard) that have not yet taken effect.

NOTE: This API returns a list of any pending updates to the cluster state. These are distinct from the tasks reported by the task management API which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create index requests. However, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task might be reported by both task api and pending cluster tasks API.

Query parameters

  • local boolean

    If true, the request retrieves information from the local node only. If false, information is retrieved from the master node.

  • Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • tasks array[object] Required
      Hide tasks attributes Show tasks attributes object
      • executing boolean Required

        Indicates whether the pending tasks are currently executing or not.

      • insert_order number Required

        The number that represents when the task has been inserted into the task queue.

      • priority string Required

        The priority of the pending task. The valid priorities in descending priority order are: IMMEDIATE > URGENT > HIGH > NORMAL > LOW > LANGUID.

      • source string Required

        A general description of the cluster task that may include a reason and origin.

      • A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

      • Time unit for milliseconds

GET /_cluster/pending_tasks
curl \
 --request GET http://api.example.com/_cluster/pending_tasks
Response examples (200)
{
  "tasks": [
    {
      "executing": true,
      "insert_order": 42.0,
      "priority": "string",
      "source": "string",
      "time_in_queue": "string",
      "": 42.0
    }
  ]
}