Elasticsearch API

Base URL
http://api.example.com

Elasticsearch provides REST APIs that are used by the UI components and can be called directly to configure and access Elasticsearch features.

Documentation source and versions

This documentation is derived from the main branch of the elasticsearch-specification repository. It is provided under license Attribution-NonCommercial-NoDerivatives 4.0 International. This documentation contains work-in-progress information for future Elastic Stack releases.

Last update on Feb 12, 2025.

This API is provided under license Apache 2.0.

Authentication

The API accepts 3 different authentication methods:

Api key auth (http_api_key)

Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:

curl -X GET "${ES_URL}/_cat/indices?v=true" \
  -H "Authorization: ApiKey ${API_KEY}"

To get API keys, use the /_security/api_key APIs.

Basic auth (http)

Basic auth tokens are constructed with the Basic keyword, followed by a space, followed by a base64-encoded string of your username:password (separated by a : colon).

Example: send a Authorization: Basic aGVsbG86aGVsbG8= HTTP header with your requests to authenticate with the API.

Bearer auth (http)

Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API. For examples, refer to Token-based authentication services

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
}

Delete an autoscaling policy Added in 7.11.0

DELETE /_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.

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 /_autoscaling/policy/{name}
curl \
 --request DELETE http://api.example.com/_autoscaling/policy/{name}
Response examples (200)
This may be a response to either `DELETE /_autoscaling/policy/my_autoscaling_policy` or `DELETE /_autoscaling/policy/*`.
{
  "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"
      }
  }
}

Create a behavioral analytics collection Technical preview

PUT /_application/analytics/{name}

Path parameters

  • name string Required

    The name of the analytics collection to be created or updated.

Responses

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

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

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




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"
      }
  }
}

Create a behavioral analytics collection event Technical preview

POST /_application/analytics/{collection_name}/event/{event_type}

Path parameters

  • collection_name string Required

    The name of the behavioral analytics collection.

  • event_type string Required

    The analytics event type.

    Values are page_view, search, or search_click.

Query parameters

  • debug boolean

    Whether the response type has to include more details

application/json

Body Required

object object

Additional properties are allowed.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
POST /_application/analytics/{collection_name}/event/{event_type}
curl \
 --request POST http://api.example.com/_application/analytics/{collection_name}/event/{event_type} \
 --header "Content-Type: application/json" \
 --data '"{\n  \"session\": {\n    \"id\": \"1797ca95-91c9-4e2e-b1bd-9c38e6f386a9\"\n  },\n  \"user\": {\n    \"id\": \"5f26f01a-bbee-4202-9298-81261067abbd\"\n  },\n  \"search\":{\n    \"query\": \"search term\",\n    \"results\": {\n      \"items\": [\n        {\n          \"document\": {\n            \"id\": \"123\",\n            \"index\": \"products\"\n          }\n        }\n      ],\n      \"total_results\": 10\n    },\n    \"sort\": {\n      \"name\": \"relevance\"\n    },\n    \"search_application\": \"website\"\n  },\n  \"document\":{\n    \"id\": \"123\",\n    \"index\": \"products\"\n  }\n}"'
Request example
Run `POST _application/analytics/my_analytics_collection/event/search_click` to send a `search_click` event to an analytics collection called `my_analytics_collection`.
{
  "session": {
    "id": "1797ca95-91c9-4e2e-b1bd-9c38e6f386a9"
  },
  "user": {
    "id": "5f26f01a-bbee-4202-9298-81261067abbd"
  },
  "search":{
    "query": "search term",
    "results": {
      "items": [
        {
          "document": {
            "id": "123",
            "index": "products"
          }
        }
      ],
      "total_results": 10
    },
    "sort": {
      "name": "relevance"
    },
    "search_application": "website"
  },
  "document":{
    "id": "123",
    "index": "products"
  }
}
Response examples (200)
{
  "accepted": true,
  "event": {}
}

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 aliases

GET /_cat/aliases/{name}

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.

Path parameters

  • name string | array[string] Required

    A comma-separated list of aliases to retrieve. Supports wildcards (*). To retrieve all aliases, omit this parameter or use * or _all.

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/{name}
curl \
 --request GET http://api.example.com/_cat/aliases/{name}
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 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.

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

Responses

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

Get component templates Added in 5.1.0

GET /_cat/component_templates

Get information about component templates in a cluster. Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

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 component template 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.

  • The period to wait for a connection to the master node.

Responses

GET /_cat/component_templates
curl \
 --request GET http://api.example.com/_cat/component_templates
Response examples (200)
[
  {
    "name": "string",
    "version": "string",
    "alias_count": "string",
    "mapping_count": "string",
    "settings_count": "string",
    "metadata_count": "string",
    "included_in": "string"
  }
]

Get component templates Added in 5.1.0

GET /_cat/component_templates/{name}

Get information about component templates in a cluster. Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.

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 component template API.

Path parameters

  • name string Required

    The name of the component template. It accepts wildcard expressions. If it is omitted, all component 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.

  • The period to wait for a connection to the master node.

Responses

GET /_cat/component_templates/{name}
curl \
 --request GET http://api.example.com/_cat/component_templates/{name}
Response examples (200)
[
  {
    "name": "string",
    "version": "string",
    "alias_count": "string",
    "mapping_count": "string",
    "settings_count": "string",
    "metadata_count": "string",
    "included_in": "string"
  }
]

Get a document count

GET /_cat/count

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.

Responses

GET /_cat/count
curl \
 --request GET http://api.example.com/_cat/count
Response examples (200)
[
  {
    "": 42.0,
    "timestamp": "string",
    "count": "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 field data cache information

GET /_cat/fielddata/{fields}

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.

Path parameters

  • fields string | array[string] Required

    Comma-separated list of fields used to limit returned information. To retrieve all fields, omit this parameter.

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












Get index information

GET /_cat/indices/{index}

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.

Path parameters

  • index string | array[string] Required

    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.

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

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.

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
curl \
 --request GET http://api.example.com/_cat/ml/data_frame/analytics
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 datafeeds Added in 7.7.0

GET /_cat/ml/datafeeds

Get configuration and usage information about datafeeds. This API returns a maximum of 10,000 datafeeds. If the Elasticsearch security features are enabled, you must have monitor_ml, monitor, manage_ml, or manage cluster privileges to use this API.

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 datafeed statistics API.

Query parameters

  • Specifies what to do when the request:

    • Contains wildcard expressions and there are no datafeeds 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 datafeeds 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.

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

Responses

  • Hide response attributes Show response attributes object
    • id string

      The datafeed identifier.

    • state string

      Values are started, stopped, starting, or stopping.

    • For started datafeeds only, contains messages relating to the selection of a node.

    • The number of buckets processed.

    • The number of searches run by the datafeed.

    • The total time the datafeed spent searching, in milliseconds.

    • The average search time per bucket, in milliseconds.

    • The exponential average search time per hour, in milliseconds.

    • node.id string

      The unique identifier of the assigned node. For started datafeeds only, this information pertains to the node upon which the datafeed is started.

    • The name of the assigned node. For started datafeeds only, this information pertains to the node upon which the datafeed is started.

    • The ephemeral identifier of the assigned node. For started datafeeds only, this information pertains to the node upon which the datafeed is started.

    • The network address of the assigned node. For started datafeeds only, this information pertains to the node upon which the datafeed is started.

GET /_cat/ml/datafeeds
curl \
 --request GET http://api.example.com/_cat/ml/datafeeds
Response examples (200)
[
  {
    "id": "string",
    "state": "started",
    "assignment_explanation": "string",
    "buckets.count": "string",
    "search.count": "string",
    "search.time": "string",
    "search.bucket_avg": "string",
    "search.exp_avg_hour": "string",
    "node.id": "string",
    "node.name": "string",
    "node.ephemeral_id": "string",
    "node.address": "string"
  }
]




Get anomaly detection jobs Added in 7.7.0

GET /_cat/ml/anomaly_detectors

Get configuration and usage information for anomaly detection jobs. This API returns a maximum of 10,000 jobs. If the Elasticsearch security features are enabled, you must have monitor_ml, monitor, manage_ml, or manage cluster privileges to use this API.

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 anomaly detection job statistics API.

Query parameters

  • Specifies what to do when the request:

    • Contains wildcard expressions and there are no jobs 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 jobs 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]

    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.

Responses

  • Hide response attributes Show response attributes object
    • id string
    • state string

      Values are closing, closed, opened, failed, or opening.

    • For open jobs only, the amount of time the job has been opened.

    • For open anomaly detection jobs only, contains messages relating to the selection of a node to run the job.

    • The number of input documents that have been processed by the anomaly detection job. This value includes documents with missing fields, since they are nonetheless analyzed. If you use datafeeds and have aggregations in your search query, the processed_record_count is the number of aggregation results processed, not the number of Elasticsearch documents.

    • The total number of fields in all the documents that have been processed by the anomaly detection job. Only fields that are specified in the detector configuration object contribute to this count. The timestamp is not included in this count.

    • The number of input documents posted to the anomaly detection job.

    • The total number of fields in input documents posted to the anomaly detection job. This count includes fields that are not used in the analysis. However, be aware that if you are using a datafeed, it extracts only the required fields from the documents it retrieves before posting them to the job.

    • The number of input documents with either a missing date field or a date that could not be parsed.

    • The number of input documents that are missing a field that the anomaly detection job is configured to analyze. Input documents with missing fields are still processed because it is possible that not all fields are missing. If you are using datafeeds or posting data to the job in JSON format, a high missing_field_count is often not an indication of data issues. It is not necessarily a cause for concern.

    • The number of input documents that have a timestamp chronologically preceding the start of the current anomaly detection bucket offset by the latency window. This information is applicable only when you provide data to the anomaly detection job by using the post data API. These out of order documents are discarded, since jobs require time series data to be in ascending chronological order.

    • The number of buckets which did not contain any data. If your data contains many empty buckets, consider increasing your bucket_span or using functions that are tolerant to gaps in data such as mean, non_null_sum or non_zero_count.

    • The number of buckets that contained few data points compared to the expected number of data points. If your data contains many sparse buckets, consider using a longer bucket_span.

    • The total number of buckets processed.

    • The timestamp of the earliest chronologically input document.

    • The timestamp of the latest chronologically input document.

    • The timestamp at which data was last analyzed, according to server time.

    • The timestamp of the last bucket that did not contain any data.

    • The timestamp of the last bucket that was considered sparse.

    • Values are ok, soft_limit, or hard_limit.

    • The upper limit for model memory usage, checked on increasing values.

    • The number of by field values that were analyzed by the models. This value is cumulative for all detectors in the job.

    • The number of over field values that were analyzed by the models. This value is cumulative for all detectors in the job.

    • The number of partition field values that were analyzed by the models. This value is cumulative for all detectors in the job.

    • The number of buckets for which new entities in incoming data were not processed due to insufficient model memory. This situation is also signified by a hard_limit: memory_status property value.

    • Values are ok or warn.

    • The number of documents that have had a field categorized.

    • The number of categories created by categorization.

    • The number of categories that match more than 1% of categorized documents.

    • The number of categories that match just one categorized document.

    • The number of categories created by categorization that will never be assigned again because another category’s definition makes it a superset of the dead category. Dead categories are a side effect of the way categorization has no prior training.

    • The number of times that categorization wanted to create a new category but couldn’t because the job had hit its model_memory_limit. This count does not track which specific categories failed to be created. Therefore you cannot use this value to determine the number of unique categories that were missed.

    • The timestamp when the model stats were gathered, according to server time.

    • The timestamp of the last record when the model stats were gathered.

    • The number of individual forecasts currently available for the job. A value of one or more indicates that forecasts exist.

    • The minimum memory usage in bytes for forecasts related to the anomaly detection job.

    • The maximum memory usage in bytes for forecasts related to the anomaly detection job.

    • The average memory usage in bytes for forecasts related to the anomaly detection job.

    • The total memory usage in bytes for forecasts related to the anomaly detection job.

    • The minimum number of model_forecast documents written for forecasts related to the anomaly detection job.

    • The maximum number of model_forecast documents written for forecasts related to the anomaly detection job.

    • The average number of model_forecast documents written for forecasts related to the anomaly detection job.

    • The total number of model_forecast documents written for forecasts related to the anomaly detection job.

    • The minimum runtime in milliseconds for forecasts related to the anomaly detection job.

    • The maximum runtime in milliseconds for forecasts related to the anomaly detection job.

    • The average runtime in milliseconds for forecasts related to the anomaly detection job.

    • The total runtime in milliseconds for forecasts related to the anomaly detection job.

    • node.id string
    • The name of the assigned node.

    • The network address of the assigned node.

    • The number of bucket results produced by the job.

    • The sum of all bucket processing times, in milliseconds.

    • The minimum of all bucket processing times, in milliseconds.

    • The maximum of all bucket processing times, in milliseconds.

    • The exponential moving average of all bucket processing times, in milliseconds.

    • The exponential moving average of bucket processing times calculated in a one hour time window, in milliseconds.

GET /_cat/ml/anomaly_detectors
curl \
 --request GET http://api.example.com/_cat/ml/anomaly_detectors
Response examples (200)
[
  {
    "id": "string",
    "state": "closing",
    "opened_time": "string",
    "assignment_explanation": "string",
    "data.processed_records": "string",
    "data.processed_fields": "string",
    "": 42.0,
    "data.input_records": "string",
    "data.input_fields": "string",
    "data.invalid_dates": "string",
    "data.missing_fields": "string",
    "data.out_of_order_timestamps": "string",
    "data.empty_buckets": "string",
    "data.sparse_buckets": "string",
    "data.buckets": "string",
    "data.earliest_record": "string",
    "data.latest_record": "string",
    "data.last": "string",
    "data.last_empty_bucket": "string",
    "data.last_sparse_bucket": "string",
    "model.memory_status": "ok",
    "model.memory_limit": "string",
    "model.by_fields": "string",
    "model.over_fields": "string",
    "model.partition_fields": "string",
    "model.bucket_allocation_failures": "string",
    "model.categorization_status": "ok",
    "model.categorized_doc_count": "string",
    "model.total_category_count": "string",
    "model.frequent_category_count": "string",
    "model.rare_category_count": "string",
    "model.dead_category_count": "string",
    "model.failed_category_count": "string",
    "model.log_time": "string",
    "model.timestamp": "string",
    "forecasts.total": "string",
    "forecasts.memory.min": "string",
    "forecasts.memory.max": "string",
    "forecasts.memory.avg": "string",
    "forecasts.memory.total": "string",
    "forecasts.records.min": "string",
    "forecasts.records.max": "string",
    "forecasts.records.avg": "string",
    "forecasts.records.total": "string",
    "forecasts.time.min": "string",
    "forecasts.time.max": "string",
    "forecasts.time.avg": "string",
    "forecasts.time.total": "string",
    "node.id": "string",
    "node.name": "string",
    "node.ephemeral_id": "string",
    "node.address": "string",
    "buckets.count": "string",
    "buckets.time.total": "string",
    "buckets.time.min": "string",
    "buckets.time.max": "string",
    "buckets.time.exp_avg": "string",
    "buckets.time.exp_avg_hour": "string"
  }
]

Get anomaly detection jobs Added in 7.7.0

GET /_cat/ml/anomaly_detectors/{job_id}

Get configuration and usage information for anomaly detection jobs. This API returns a maximum of 10,000 jobs. If the Elasticsearch security features are enabled, you must have monitor_ml, monitor, manage_ml, or manage cluster privileges to use this API.

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 anomaly detection job statistics API.

Path parameters

  • job_id string Required

    Identifier for the anomaly detection job.

Query parameters

  • Specifies what to do when the request:

    • Contains wildcard expressions and there are no jobs 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 jobs 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]

    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.

Responses

  • Hide response attributes Show response attributes object
    • id string
    • state string

      Values are closing, closed, opened, failed, or opening.

    • For open jobs only, the amount of time the job has been opened.

    • For open anomaly detection jobs only, contains messages relating to the selection of a node to run the job.

    • The number of input documents that have been processed by the anomaly detection job. This value includes documents with missing fields, since they are nonetheless analyzed. If you use datafeeds and have aggregations in your search query, the processed_record_count is the number of aggregation results processed, not the number of Elasticsearch documents.

    • The total number of fields in all the documents that have been processed by the anomaly detection job. Only fields that are specified in the detector configuration object contribute to this count. The timestamp is not included in this count.

    • The number of input documents posted to the anomaly detection job.

    • The total number of fields in input documents posted to the anomaly detection job. This count includes fields that are not used in the analysis. However, be aware that if you are using a datafeed, it extracts only the required fields from the documents it retrieves before posting them to the job.

    • The number of input documents with either a missing date field or a date that could not be parsed.

    • The number of input documents that are missing a field that the anomaly detection job is configured to analyze. Input documents with missing fields are still processed because it is possible that not all fields are missing. If you are using datafeeds or posting data to the job in JSON format, a high missing_field_count is often not an indication of data issues. It is not necessarily a cause for concern.

    • The number of input documents that have a timestamp chronologically preceding the start of the current anomaly detection bucket offset by the latency window. This information is applicable only when you provide data to the anomaly detection job by using the post data API. These out of order documents are discarded, since jobs require time series data to be in ascending chronological order.

    • The number of buckets which did not contain any data. If your data contains many empty buckets, consider increasing your bucket_span or using functions that are tolerant to gaps in data such as mean, non_null_sum or non_zero_count.

    • The number of buckets that contained few data points compared to the expected number of data points. If your data contains many sparse buckets, consider using a longer bucket_span.

    • The total number of buckets processed.

    • The timestamp of the earliest chronologically input document.

    • The timestamp of the latest chronologically input document.

    • The timestamp at which data was last analyzed, according to server time.

    • The timestamp of the last bucket that did not contain any data.

    • The timestamp of the last bucket that was considered sparse.

    • Values are ok, soft_limit, or hard_limit.

    • The upper limit for model memory usage, checked on increasing values.

    • The number of by field values that were analyzed by the models. This value is cumulative for all detectors in the job.

    • The number of over field values that were analyzed by the models. This value is cumulative for all detectors in the job.

    • The number of partition field values that were analyzed by the models. This value is cumulative for all detectors in the job.

    • The number of buckets for which new entities in incoming data were not processed due to insufficient model memory. This situation is also signified by a hard_limit: memory_status property value.

    • Values are ok or warn.

    • The number of documents that have had a field categorized.

    • The number of categories created by categorization.

    • The number of categories that match more than 1% of categorized documents.

    • The number of categories that match just one categorized document.

    • The number of categories created by categorization that will never be assigned again because another category’s definition makes it a superset of the dead category. Dead categories are a side effect of the way categorization has no prior training.

    • The number of times that categorization wanted to create a new category but couldn’t because the job had hit its model_memory_limit. This count does not track which specific categories failed to be created. Therefore you cannot use this value to determine the number of unique categories that were missed.

    • The timestamp when the model stats were gathered, according to server time.

    • The timestamp of the last record when the model stats were gathered.

    • The number of individual forecasts currently available for the job. A value of one or more indicates that forecasts exist.

    • The minimum memory usage in bytes for forecasts related to the anomaly detection job.

    • The maximum memory usage in bytes for forecasts related to the anomaly detection job.

    • The average memory usage in bytes for forecasts related to the anomaly detection job.

    • The total memory usage in bytes for forecasts related to the anomaly detection job.

    • The minimum number of model_forecast documents written for forecasts related to the anomaly detection job.

    • The maximum number of model_forecast documents written for forecasts related to the anomaly detection job.

    • The average number of model_forecast documents written for forecasts related to the anomaly detection job.

    • The total number of model_forecast documents written for forecasts related to the anomaly detection job.

    • The minimum runtime in milliseconds for forecasts related to the anomaly detection job.

    • The maximum runtime in milliseconds for forecasts related to the anomaly detection job.

    • The average runtime in milliseconds for forecasts related to the anomaly detection job.

    • The total runtime in milliseconds for forecasts related to the anomaly detection job.

    • node.id string
    • The name of the assigned node.

    • The network address of the assigned node.

    • The number of bucket results produced by the job.

    • The sum of all bucket processing times, in milliseconds.

    • The minimum of all bucket processing times, in milliseconds.

    • The maximum of all bucket processing times, in milliseconds.

    • The exponential moving average of all bucket processing times, in milliseconds.

    • The exponential moving average of bucket processing times calculated in a one hour time window, in milliseconds.

GET /_cat/ml/anomaly_detectors/{job_id}
curl \
 --request GET http://api.example.com/_cat/ml/anomaly_detectors/{job_id}
Response examples (200)
[
  {
    "id": "string",
    "state": "closing",
    "opened_time": "string",
    "assignment_explanation": "string",
    "data.processed_records": "string",
    "data.processed_fields": "string",
    "": 42.0,
    "data.input_records": "string",
    "data.input_fields": "string",
    "data.invalid_dates": "string",
    "data.missing_fields": "string",
    "data.out_of_order_timestamps": "string",
    "data.empty_buckets": "string",
    "data.sparse_buckets": "string",
    "data.buckets": "string",
    "data.earliest_record": "string",
    "data.latest_record": "string",
    "data.last": "string",
    "data.last_empty_bucket": "string",
    "data.last_sparse_bucket": "string",
    "model.memory_status": "ok",
    "model.memory_limit": "string",
    "model.by_fields": "string",
    "model.over_fields": "string",
    "model.partition_fields": "string",
    "model.bucket_allocation_failures": "string",
    "model.categorization_status": "ok",
    "model.categorized_doc_count": "string",
    "model.total_category_count": "string",
    "model.frequent_category_count": "string",
    "model.rare_category_count": "string",
    "model.dead_category_count": "string",
    "model.failed_category_count": "string",
    "model.log_time": "string",
    "model.timestamp": "string",
    "forecasts.total": "string",
    "forecasts.memory.min": "string",
    "forecasts.memory.max": "string",
    "forecasts.memory.avg": "string",
    "forecasts.memory.total": "string",
    "forecasts.records.min": "string",
    "forecasts.records.max": "string",
    "forecasts.records.avg": "string",
    "forecasts.records.total": "string",
    "forecasts.time.min": "string",
    "forecasts.time.max": "string",
    "forecasts.time.avg": "string",
    "forecasts.time.total": "string",
    "node.id": "string",
    "node.name": "string",
    "node.ephemeral_id": "string",
    "node.address": "string",
    "buckets.count": "string",
    "buckets.time.total": "string",
    "buckets.time.min": "string",
    "buckets.time.max": "string",
    "buckets.time.exp_avg": "string",
    "buckets.time.exp_avg_hour": "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 trained models Added in 7.7.0

GET /_cat/ml/trained_models/{model_id}

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.

Path parameters

  • model_id string Required

    A unique identifier for the trained model.

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/{model_id}
curl \
 --request GET http://api.example.com/_cat/ml/trained_models/{model_id}
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 plugin information

GET /_cat/plugins

Get a list of plugins running on each node of a 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 info API.

Query parameters

  • Include bootstrap plugins in the response

  • 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/plugins
curl \
 --request GET http://api.example.com/_cat/plugins
Response examples (200)
[
  {
    "id": "string",
    "name": "string",
    "component": "string",
    "version": "string",
    "description": "string",
    "type": "string"
  }
]

Get shard recovery information

GET /_cat/recovery

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.

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
curl \
 --request GET http://api.example.com/_cat/recovery
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 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 segment information

GET /_cat/segments

Get low-level information about the Lucene segments in index shards. 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. For application consumption, use the index segments API.

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

  • Hide response attributes Show response attributes object
    • index string
    • shard string

      The shard name.

    • prirep string

      The shard type: primary or replica.

    • ip string

      The IP address of the node where it lives.

    • id string
    • segment string

      The segment name, which is derived from the segment generation and used internally to create file names in the directory of the shard.

    • The segment generation number. Elasticsearch increments this generation number for each segment written then uses this number to derive the segment name.

    • The number of documents in the segment. This excludes deleted documents and counts any nested documents separately from their parents. It also excludes documents which were indexed recently and do not yet belong to a segment.

    • The number of deleted documents in the segment, which might be higher or lower than the number of delete operations you have performed. This number excludes deletes that were performed recently and do not yet belong to a segment. Deleted documents are cleaned up by the automatic merge process if it makes sense to do so. Also, Elasticsearch creates extra deleted documents to internally track the recent history of operations on a shard.

    • If true, the segment is synced to disk. Segments that are synced can survive a hard reboot. If false, the data from uncommitted segments is also stored in the transaction log so that Elasticsearch is able to replay changes on the next start.

    • If true, the segment is searchable. If false, the segment has most likely been written to disk but needs a refresh to be searchable.

    • version string
    • compound string

      If true, the segment is stored in a compound file. This means Lucene merged all files from the segment in a single file to save file descriptors.

GET /_cat/segments
curl \
 --request GET http://api.example.com/_cat/segments
Response examples (200)
[
  {
    "index": "string",
    "shard": "string",
    "prirep": "string",
    "ip": "string",
    "id": "string",
    "segment": "string",
    "generation": "string",
    "docs.count": "string",
    "docs.deleted": "string",
    "": 42.0,
    "committed": "string",
    "searchable": "string",
    "version": "string",
    "compound": "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 index template information Added in 5.2.0

GET /_cat/templates

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.

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
curl \
 --request GET http://api.example.com/_cat/templates
Response examples (200)
[
  {
    "name": "string",
    "index_patterns": "string",
    "order": "string",
    "version": "string",
    "composed_of": "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

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.

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
curl \
 --request GET http://api.example.com/_cat/thread_pool
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 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/{transform_id}

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.

Path parameters

  • transform_id string Required

    A transform identifier or a wildcard expression. If you do not specify one of these options, the API returns information for all transforms.

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