Get the autoscaling capacity Added in 7.11.0

GET /_autoscaling/capacity

Api key auth Basic auth Bearer auth

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.

External documentation

Query parameters

master_timeout string

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
  
  Hide * attributes Show * attributes object
  
  required_capacity object Required
  
  Hide required_capacity attributes Show required_capacity attributes object
  
  node object Required
  
  Hide node attributes Show node attributes object
  
  storage number Required
  
  memory number Required
  
  total object Required
  
  Hide total attributes Show total attributes object
  
  storage number Required
  
  memory number Required
  
  current_capacity object Required
  
  Hide current_capacity attributes Show current_capacity attributes object
  
  node object Required
  
  Hide node attributes Show node attributes object
  
  storage number Required
  
  memory number Required
  
  total object Required
  
  Hide total attributes Show total attributes object
  
  storage number Required
  
  memory number Required
  
  current_nodes array[object] Required
  
  Hide current_nodes attribute Show current_nodes attribute object
  
  name string Required
  
  deciders object Required
  
  Hide deciders attribute Show deciders attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  required_capacity object Required
  
  Hide required_capacity attributes Show required_capacity attributes object
  
  node object Required
  
  total object Required
  
  reason_summary string
  
  reason_details object

GET /_autoscaling/capacity

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

Response examples (200)

This may be a response to `GET /_autoscaling/capacity`.

{
  policies: {}
}

Create a behavioral analytics collection Technical preview

PUT /_application/analytics/{name}

Api key auth Basic auth Bearer auth

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}' \
 --header "Authorization: $API_KEY"

Delete a behavioral analytics collection Technical preview

DELETE /_application/analytics/{name}

Api key auth Basic auth Bearer auth

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}' \
 --header "Authorization: $API_KEY"

Get behavioral analytics collections Technical preview

GET /_application/analytics

Api key auth Basic auth Bearer auth

Responses

200 application/json
Hide response attribute Show response attribute object
- * object Additional properties
  
  Hide * attribute Show * attribute object
  
  event_data_stream object Required
  
  Hide event_data_stream attribute Show event_data_stream attribute object
  
  name string Required

GET /_application/analytics

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

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}

Api key auth Basic auth Bearer auth

External documentation

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

Responses

200 application/json
Hide response attributes Show response attributes object
- accepted boolean Required
- event object

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

curl \
 --request POST 'http://api.example.com/_application/analytics/{collection_name}/event/{event_type}' \
 --header "Authorization: $API_KEY" \
 --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"
  }
}

Get aliases

GET /_cat/aliases

Api key auth Basic auth Bearer auth

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

h string | array[string]

List of columns to appear in the response. Supports simple wildcards.
s string | array[string]

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.
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.
local boolean

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

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

200 application/json
Hide response attributes Show response attributes object
- alias string
  
  alias name
- index string
- filter string
  
  filter
- routing.index string
  
  index routing
- routing.search string
  
  search routing
- is_write_index string
  
  write index

GET /_cat/aliases

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

Response examples (200)

A successful response from `GET _cat/aliases?format=json&v=true`. This response shows that `alias2` has configured a filter and `alias3` and `alias4` have routing configurations.

[
  {
    "alias": "alias1",
    "index": "test1",
    "filter": "-",
    "routing.index": "-",
    "routing.search": "-",
    "is_write_index": "true"
  },
  {
    "alias": "alias1",
    "index": "test1",
    "filter": "*",
    "routing.index": "-",
    "routing.search": "-",
    "is_write_index": "true"
  },
  {
    "alias": "alias3",
    "index": "test1",
    "filter": "-",
    "routing.index": "1",
    "routing.search": "1",
    "is_write_index": "true"
  },
  {
    "alias": "alias4",
    "index": "test1",
    "filter": "-",
    "routing.index": "2",
    "routing.search": "1,2",
    "is_write_index": "true"
  }
]

Get a document count

GET /_cat/count/{index}

Api key auth Basic auth Bearer auth

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

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

Path parameters

index string | array[string] Required

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

Query parameters

h string | array[string]

List of columns to appear in the response. Supports simple wildcards.
s string | array[string]

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.

Responses

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

GET /_cat/count/{index}

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

Response examples (200)

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

[
  {
    "epoch": "1475868259",
    "timestamp": "15:24:20",
    "count": "120"
  }
]

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

[
  {
    "epoch": "1475868259",
    "timestamp": "15:24:20",
    "count": "121"
  }
]

Get field data cache information

GET /_cat/fielddata/{fields}

Api key auth Basic auth Bearer auth

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.
h string | array[string]

List of columns to appear in the response. Supports simple wildcards.
s string | array[string]

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.

Responses

200 application/json
Hide response attributes Show response attributes object
- id string
  
  node id
- host string
  
  host name
- ip string
  
  ip address
- node string
  
  node name
- field string
  
  field name
- size string
  
  field data usage

GET /_cat/fielddata/{fields}

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

Response examples (200)

A successful response from `GET /_cat/fielddata?v=true&fields=body&format=json`. You can specify an individual field in the request body or URL path. This example retrieves heap memory size information for the `body` field.

[
  {
    "id": "Nqk-6inXQq-OxUfOUI8jNQ",
    "host": "127.0.0.1",
    "ip": "127.0.0.1",
    "node": "Nqk-6in",
    "field": "body",
    "size": "544b"
  }
]

A successful response from `GET /_cat/fielddata/body,soul?v=true&format=json`. You can specify a comma-separated list of fields in the request body or URL path. This example retrieves heap memory size information for the `body` and `soul` fields. To get information for all fields, run `GET /_cat/fielddata?v=true`.

[
  {
    "id": "Nqk-6inXQq-OxUfOUI8jNQ",
    "host": "1127.0.0.1",
    "ip": "127.0.0.1",
    "node": "Nqk-6in",
    "field": "body",
    "size": "544b"
  },
  {
    "id": "Nqk-6inXQq-OxUfOUI8jNQ",
    "host": "127.0.0.1",
    "ip": "127.0.0.1",
    "node": "Nqk-6in",
    "field": "soul",
    "size": "480b"
  }
]

Get data frame analytics jobs Added in 7.7.0

GET /_cat/ml/data_frame/analytics

Api key auth Basic auth Bearer auth

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

allow_no_match boolean

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

200 application/json
Hide response attributes Show response attributes object
- id string
- type string
  
  The type of analysis that the job performs.
- create_time string
  
  The time when the job was created.
- version string
- source_index string
- dest_index string
- description string
  
  A description of the job.
- model_memory_limit string
  
  The approximate maximum amount of memory resources that are permitted for the job.
- state string
  
  The current status of the job.
- failure_reason string
  
  Messages about the reason why the job failed.
- progress string
  
  The progress report for the job by phase.
- assignment_explanation string
  
  Messages related to the selection of a node.
- node.id string
- node.name string
- node.ephemeral_id string
- node.address string
  
  The network address of the assigned node.

GET /_cat/ml/data_frame/analytics

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

Response examples (200)

A successful response from `GET _cat/ml/data_frame/analytics?v=true&format=json`.

[
  {
    "id": "classifier_job_1",
    "type": "classification",
    "create_time": "2020-02-12T11:49:09.594Z",
    "state": "stopped"
  },
    {
    "id": "classifier_job_2",
    "type": "classification",
    "create_time": "2020-02-12T11:49:14.479Z",
    "state": "stopped"
  },
  {
    "id": "classifier_job_3",
    "type": "classification",
    "create_time": "2020-02-12T11:49:16.928Z",
    "state": "stopped"
  },
  {
    "id": "classifier_job_4",
    "type": "classification",
    "create_time": "2020-02-12T11:49:19.127Z",
    "state": "stopped"
  },
  {
    "id": "classifier_job_5",
    "type": "classification",
    "create_time": "2020-02-12T11:49:21.349Z",
    "state": "stopped"
  }
]

Get node attribute information

GET /_cat/nodeattrs

Api key auth Basic auth Bearer auth

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

h string | array[string]

List of columns to appear in the response. Supports simple wildcards.
s string | array[string]

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.
local boolean

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

Period to wait for a connection to the master node.

Responses

200 application/json
Hide response attributes Show response attributes object
- node string
  
  The node name.
- id string
  
  The unique node identifier.
- pid string
  
  The process identifier.
- host string
  
  The host name.
- ip string
  
  The IP address.
- port string
  
  The bound transport port.
- attr string
  
  The attribute name.
- value string
  
  The attribute value.

GET /_cat/nodeattrs

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

Response examples (200)

A successful response from `GET /_cat/nodeattrs?v=true&format=json`. The `node`, `host`, and `ip` columns provide basic information about each node. The `attr` and `value` columns return custom node attributes, one per line.

[
  {
    "node": "node-0",
    "host": "127.0.0.1",
    "ip": "127.0.0.1",
    "attr": "testattr",
    "value": "test"
  }
]

A successful response from `GET /_cat/nodeattrs?v=true&h=name,pid,attr,value`. It returns the `name`, `pid`, `attr`, and `value` columns.

[
  {
    "name": "node-0",
    "pid": "19566",
    "attr": "testattr",
    "value": "test"
  }
]

Get snapshot information Added in 2.1.0

GET /_cat/snapshots

Api key auth Basic auth Bearer auth

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

ignore_unavailable boolean

If true, the response does not include information from unavailable snapshots.
h string | array[string]

List of columns to appear in the response. Supports simple wildcards.
s string | array[string]

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.
master_timeout string

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

200 application/json
Hide response attributes Show response attributes object
- id string
  
  The unique identifier for the snapshot.
- repository string
  
  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.
  
  One of:
  UnitSeconds number StringifiedEpochTimeUnitSeconds string
  
  Time unit for seconds
- start_time string | object
  
  A time of day, expressed either as hh:mm, noon, midnight, or an hour/minutes structure.
  
  One of:
  ScheduleTimeOfDay string HourAndMinute object
- 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.
  
  One of:
  UnitSeconds number StringifiedEpochTimeUnitSeconds string
  
  Time unit for seconds
- 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.
- successful_shards string
  
  The number of successful shards in the snapshot.
- failed_shards string
  
  The number of failed shards in the snapshot.
- total_shards string
  
  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' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `GET /_cat/snapshots/repo1?v=true&s=id&format=json`.

[
  {
    "id": "snap1",
    "repository": "repo1",
    "status": "FAILED",
    "start_epoch": "1445616705",
    "start_time": "18:11:45",
    "end_epoch": "1445616978",
    "end_time": "18:16:18",
    "duration": "4.6m",
    "indices": "1",
    "successful_shards": "4",
    "failed_shards": "1",
    "total_shards": "5"
  },
  {
    "id": "snap2",
    "repository": "repo1",
    "status": "SUCCESS",
    "start_epoch": "1445634298",
    "start_time": "23:04:58",
    "end_epoch": "1445634672",
    "end_time": "23:11:12",
    "duration": "6.2m",
    "indices": "2",
    "successful_shards": "10",
    "failed_shards": "0",
    "total_shards": "10"
  }
]

Get task information Technical preview

GET /_cat/tasks

Api key auth Basic auth Bearer auth

Get information about tasks currently running 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 task management API.

Query parameters

actions array[string]

The task action names, which are used to limit the response.
detailed boolean

If true, the response includes detailed information about shard recoveries.
nodes array[string]

Unique node identifiers, which are used to limit the response.
parent_task_id string

The parent task identifier, which is used to limit the response.
h string | array[string]

List of columns to appear in the response. Supports simple wildcards.
s string | array[string]

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.
time string

Unit used to display time values.

Values are nanos, micros, ms, s, m, h, or d.
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_completion boolean

If true, the request blocks until the task has completed.

Responses

200 application/json
Hide response attributes Show response attributes object
- id string
- action string
  
  The task action.
- task_id string
- parent_task_id string
  
  The parent task identifier.
- type string
  
  The task type.
- start_time string
  
  The start time in milliseconds.
- timestamp string
  
  The start time in HH:MM:SS format.
- running_time_ns string
  
  The running time in nanoseconds.
- running_time string
  
  The running time.
- node_id string
- ip string
  
  The IP address for the node.
- port string
  
  The bound transport port for the node.
- node string
  
  The node name.
- version string
- x_opaque_id string
  
  The X-Opaque-ID header.
- description string
  
  The task action description.

GET /_cat/tasks

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

Response examples (200)

A successful response from `GET _cat/tasks?v=true&format=json`.

[
  {
    "action": "cluster:monitor/tasks/lists[n]",
    "task_id": "oTUltX4IQMOUUVeiohTt8A:124",
    "parent_task_id": "oTUltX4IQMOUUVeiohTt8A:123",
    "type": "direct",
    "start_time": "1458585884904",
    "timestamp": "01:48:24",
    "running_time": "44.1micros",
    "ip": "127.0.0.1:9300",
    "node": "oTUltX4IQMOUUVeiohTt8A"
  },
  {
    "action": "cluster:monitor/tasks/lists",
    "task_id": "oTUltX4IQMOUUVeiohTt8A:123",
    "parent_task_id": "-",
    "type": "transport",
    "start_time": "1458585884904",
    "timestamp": "01:48:24",
    "running_time": "186.2micros",
    "ip": "127.0.0.1:9300",
    "node": "oTUltX4IQMOUUVeiohTt8A"
  }
]

Get index template information Added in 5.2.0

GET /_cat/templates/{name}

Api key auth Basic auth Bearer auth

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

h string | array[string]

List of columns to appear in the response. Supports simple wildcards.
s string | array[string]

List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.
local boolean

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

Period to wait for a connection to the master node.

Responses

200 application/json
Hide response attributes Show response attributes object
- name string
- index_patterns string
  
  The template index patterns.
- order string
  
  The template application order or priority number.
- version string | null
  
  The template version.
  
  One of:
  VersionString string string-2 string | null
- composed_of string
  
  The component templates that comprise the index template.

GET /_cat/templates/{name}

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

Response examples (200)

A successful response from `GET _cat/templates/my-template-*?v=true&s=name&format=json`.

[
  {
    "name": "my-template-0",
    "index_patterns": "[te*]",
    "order": "500",
    "version": null,
    "composed_of": "[]"
  },
  {
    "name": "my-template-1",
    "index_patterns": "[tea*]",
    "order": "501",
    "version": null,
    "composed_of": "[]"
  },
  {
    "name": "my-template-2",
    "index_patterns": "[teak*]",
    "order": "502",
    "version": "7",
    "composed_of": "[]"
  }
]

Update the cluster settings

PUT /_cluster/settings

Api key auth Basic auth Bearer auth

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

flat_settings boolean

Return settings in flat format (default: false)
master_timeout string

Explicit operation timeout for connection to master node
timeout string

Explicit operation timeout

application/json

Body Required

persistent object
Hide persistent attribute Show persistent attribute object
- * object Additional properties
transient object
Hide transient attribute Show transient attribute object
- * object Additional properties

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
- transient object Required
  
  Hide transient attribute Show transient attribute object
  
  * object Additional properties

PUT /_cluster/settings

curl \
 --request PUT 'http://api.example.com/_cluster/settings' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"persistent\" : {\n    \"indices.recovery.max_bytes_per_sec\" : \"50mb\"\n  }\n}"'

Request examples

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

Get the pending cluster tasks

GET /_cluster/pending_tasks

Api key auth Basic auth Bearer auth

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.
master_timeout string

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.
  
  time_in_queue 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.
  
  time_in_queue_millis number
  
  Time unit for milliseconds

GET /_cluster/pending_tasks

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

Get the cluster state Added in 1.3.0

GET /_cluster/state

Api key auth Basic auth Bearer auth

Get comprehensive information about the state of the cluster.

The cluster state is an internal data structure which keeps track of a variety of information needed by every node, including the identity and attributes of the other nodes in the cluster; cluster-wide settings; index metadata, including the mapping and settings for each index; the location and status of every shard copy in the cluster.

The elected master node ensures that every node in the cluster has a copy of the same cluster state. This API lets you retrieve a representation of this internal state for debugging or diagnostic purposes. You may need to consult the Elasticsearch source code to determine the precise meaning of the response.

By default the API will route requests to the elected master node since this node is the authoritative source of cluster states. You can also retrieve the cluster state held on the node handling the API request by adding the ?local=true query parameter.

Elasticsearch may need to expend significant effort to compute a response to this API in larger clusters, and the response may comprise a very large quantity of data. If you use this API repeatedly, your cluster may become unstable.

WARNING: The response is a representation of an internal data structure. Its format is not subject to the same compatibility guarantees as other more stable APIs and may change from version to version. Do not query this API using external monitoring tools. Instead, obtain the information you require using other more stable cluster APIs.

Query parameters

allow_no_indices boolean

Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes _all string or when no indices have been specified)
expand_wildcards string | array[string]

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

Return settings in flat format (default: false)
ignore_unavailable boolean

Whether specified concrete indices should be ignored when unavailable (missing or closed)
local boolean

Return local information, do not retrieve the state from master node (default: false)
master_timeout string

Specify timeout for connection to master
wait_for_metadata_version number

Wait for the metadata version to be equal or greater than the specified metadata version
wait_for_timeout string

The maximum time to wait for wait_for_metadata_version before timing out

Responses

200 application/json

GET /_cluster/state

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

Ping the cluster

HEAD /

Api key auth Basic auth Bearer auth

Get information about whether the cluster is running.

Responses

200 application/json

HEAD /

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

Clear the archived repositories metering Technical preview

DELETE /_nodes/{node_id}/_repositories_metering/{max_archive_version}

Api key auth Basic auth Bearer auth

Clear the archived repositories metering information in the cluster.

Path parameters

node_id string | array[string] Required

Comma-separated list of node IDs or names used to limit returned information.
max_archive_version number Required

Specifies the maximum archive_version to be cleared from the archive.

Responses

200 application/json
Hide response attributes Show response attributes object
- _nodes object
  
  Hide _nodes attributes Show _nodes attributes object
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  total number Required
  
  Total number of nodes selected by the request.
  
  successful number Required
  
  Number of nodes that responded successfully to the request.
  
  failed number Required
  
  Number of nodes that rejected the request or failed to respond. If this value is not 0, a reason for the rejection or failure is included in the response.
- cluster_name string Required
- nodes object Required
  
  Contains repositories metering information for the nodes selected by the request.
  
  Hide nodes attribute Show nodes attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  repository_name string Required
  
  repository_type string Required
  
  Repository type.
  
  repository_location object Required
  
  Hide repository_location attributes Show repository_location attributes object
  
  base_path string Required
  
  container string
  
  Container name (Azure)
  
  bucket string
  
  Bucket name (GCP, S3)
  
  repository_ephemeral_id string Required
  
  Time unit for milliseconds
  
  Time unit for milliseconds
  
  archived boolean Required
  
  A flag that tells whether or not this object has been archived. When a repository is closed or updated the repository metering information is archived and kept for a certain period of time. This allows retrieving the repository metering information of previous repository instantiations.
  
  cluster_version number
  
  request_counts object Required
  
  Hide request_counts attributes Show request_counts attributes object
  
  GetBlobProperties number
  
  Number of Get Blob Properties requests (Azure)
  
  GetBlob number
  
  Number of Get Blob requests (Azure)
  
  ListBlobs number
  
  Number of List Blobs requests (Azure)
  
  PutBlob number
  
  Number of Put Blob requests (Azure)
  
  PutBlock number
  
  Number of Put Block (Azure)
  
  PutBlockList number
  
  Number of Put Block List requests
  
  GetObject number
  
  Number of get object requests (GCP, S3)
  
  ListObjects number
  
  Number of list objects requests (GCP, S3)
  
  InsertObject number
  
  Number of insert object requests, including simple, multipart and resumable uploads. Resumable uploads can perform multiple http requests to insert a single object but they are considered as a single request since they are billed as an individual operation. (GCP)
  
  PutObject number
  
  Number of PutObject requests (S3)
  
  PutMultipartObject number
  
  Number of Multipart requests, including CreateMultipartUpload, UploadPart and CompleteMultipartUpload requests (S3)

DELETE /_nodes/{node_id}/_repositories_metering/{max_archive_version}

curl \
 --request DELETE 'http://api.example.com/_nodes/{node_id}/_repositories_metering/{max_archive_version}' \
 --header "Authorization: $API_KEY"

Get the hot threads for nodes

GET /_nodes/hot_threads

Api key auth Basic auth Bearer auth

Get a breakdown of the hot threads on each selected node in the cluster. The output is plain text with a breakdown of the top hot threads for each node.

Query parameters

ignore_idle_threads boolean

If true, known idle threads (e.g. waiting in a socket select, or to get a task from an empty queue) are filtered out.
interval string

The interval to do the second sampling of threads.
snapshots number

Number of samples of thread stacktrace.
threads number

Specifies the number of hot threads to provide information for.
timeout string

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

The type to sample.

Values are cpu, wait, block, gpu, or mem.
sort string

The sort order for 'cpu' type (default: total)

Values are cpu, wait, block, gpu, or mem.

Responses

200 application/json

GET /_nodes/hot_threads

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

Get the hot threads for nodes

GET /_nodes/{node_id}/hot_threads

Api key auth Basic auth Bearer auth

Get a breakdown of the hot threads on each selected node in the cluster. The output is plain text with a breakdown of the top hot threads for each node.

Path parameters

node_id string | array[string] Required

List of node IDs or names used to limit returned information.

Query parameters

ignore_idle_threads boolean

If true, known idle threads (e.g. waiting in a socket select, or to get a task from an empty queue) are filtered out.
interval string

The interval to do the second sampling of threads.
snapshots number

Number of samples of thread stacktrace.
threads number

Specifies the number of hot threads to provide information for.
timeout string

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

The type to sample.

Values are cpu, wait, block, gpu, or mem.
sort string

The sort order for 'cpu' type (default: total)

Values are cpu, wait, block, gpu, or mem.

Responses

200 application/json

GET /_nodes/{node_id}/hot_threads

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

Reload the keystore on nodes in the cluster Added in 6.5.0

POST /_nodes/reload_secure_settings

Api key auth Basic auth Bearer auth

Secure settings are stored in an on-disk keystore. Certain of these settings are reloadable. That is, you can change them on disk and reload them without restarting any nodes in the cluster. When you have updated reloadable secure settings in your keystore, you can use this API to reload those settings on each node.

When the Elasticsearch keystore is password protected and not simply obfuscated, you must provide the password for the keystore when you reload the secure settings. Reloading the settings for the whole cluster assumes that the keystores for all nodes are protected with the same password; this method is allowed only when inter-node communications are encrypted. Alternatively, you can reload the secure settings on each node by locally accessing the API and passing the node-specific Elasticsearch keystore password.

Query parameters

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

secure_settings_password string

Responses

200 application/json
Hide response attributes Show response attributes object
- _nodes object
  
  Hide _nodes attributes Show _nodes attributes object
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  total number Required
  
  Total number of nodes selected by the request.
  
  successful number Required
  
  Number of nodes that responded successfully to the request.
  
  failed number Required
  
  Number of nodes that rejected the request or failed to respond. If this value is not 0, a reason for the rejection or failure is included in the response.
- cluster_name string Required
- nodes object Required
  
  Hide nodes attribute Show nodes attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  name string Required
  
  reload_exception object
  
  Hide reload_exception attributes Show reload_exception attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]

POST /_nodes/reload_secure_settings

curl \
 --request POST 'http://api.example.com/_nodes/reload_secure_settings' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"secure_settings_password\": \"keystore-password\"\n}"'

Request example

Run `POST _nodes/reload_secure_settings` to reload the keystore on nodes in the cluster.

{
  "secure_settings_password": "keystore-password"
}

Response examples (200)

A successful response when reloading keystore on nodes in your cluster.

{
  "_nodes": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "cluster_name": "my_cluster",
  "nodes": {
    "pQHNt5rXTTWNvUgOrdynKg": {
      "name": "node-0"
    }
  }
}

Get feature usage information Added in 6.0.0

GET /_nodes/{node_id}/usage

Api key auth Basic auth Bearer auth

Path parameters

node_id string | array[string] Required

A comma-separated list of node IDs or names to limit the returned information; use _local to return information from the node you're connecting to, leave empty to get information from all nodes

Query parameters

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 attributes Show response attributes object
- _nodes object
  
  Hide _nodes attributes Show _nodes attributes object
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  total number Required
  
  Total number of nodes selected by the request.
  
  successful number Required
  
  Number of nodes that responded successfully to the request.
  
  failed number Required
  
  Number of nodes that rejected the request or failed to respond. If this value is not 0, a reason for the rejection or failure is included in the response.
- cluster_name string Required
- nodes object Required
  
  Hide nodes attribute Show nodes attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  rest_actions object Required
  
  Hide rest_actions attribute Show rest_actions attribute object
  
  * number Additional properties
  
  Time unit for milliseconds
  
  Time unit for milliseconds
  
  aggregations object Required
  
  Hide aggregations attribute Show aggregations attribute object
  
  * object Additional properties

GET /_nodes/{node_id}/usage

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

Get feature usage information Added in 6.0.0

GET /_nodes/usage/{metric}

Api key auth Basic auth Bearer auth

Path parameters

metric string | array[string] Required

Limits the information returned to the specific metrics. A comma-separated list of the following options: _all, rest_actions.

Query parameters

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 attributes Show response attributes object
- _nodes object
  
  Hide _nodes attributes Show _nodes attributes object
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  total number Required
  
  Total number of nodes selected by the request.
  
  successful number Required
  
  Number of nodes that responded successfully to the request.
  
  failed number Required
  
  Number of nodes that rejected the request or failed to respond. If this value is not 0, a reason for the rejection or failure is included in the response.
- cluster_name string Required
- nodes object Required
  
  Hide nodes attribute Show nodes attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  rest_actions object Required
  
  Hide rest_actions attribute Show rest_actions attribute object
  
  * number Additional properties
  
  Time unit for milliseconds
  
  Time unit for milliseconds
  
  aggregations object Required
  
  Hide aggregations attribute Show aggregations attribute object
  
  * object Additional properties

GET /_nodes/usage/{metric}

curl \
 --request GET 'http://api.example.com/_nodes/usage/{metric}' \
 --header "Authorization: $API_KEY"

Connector

The connector and sync jobs APIs provide a convenient way to create and manage Elastic connectors and sync jobs in an internal index. Connectors are Elasticsearch integrations that bring content from third-party data sources, which can be deployed on Elastic Cloud or hosted on your own infrastructure:

Elastic managed connectors (Native connectors) are a managed service on Elastic Cloud
Self-managed connectors (Connector clients) are self-managed on your infrastructure.

This API provides an alternative to relying solely on Kibana UI for connector and sync job management. The API comes with a set of validations and assertions to ensure that the state representation in the internal index remains valid.

Check out the connector API tutorial

Check in a connector Technical preview

PUT /_connector/{connector_id}/_check_in

Api key auth Basic auth Bearer auth

Update the last_seen field in the connector and set it to the current timestamp.

Path parameters

connector_id string Required

The unique identifier of the connector to be checked in

Responses

200 application/json
Hide response attribute Show response attribute object
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.

PUT /_connector/{connector_id}/_check_in

curl \
 --request PUT 'http://api.example.com/_connector/{connector_id}/_check_in' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
    "result": "updated"
}

Create a connector Beta

POST /_connector

Api key auth Basic auth Bearer auth

Connectors are Elasticsearch integrations that bring content from third-party data sources, which can be deployed on Elastic Cloud or hosted on your own infrastructure. Elastic managed connectors (Native connectors) are a managed service on Elastic Cloud. Self-managed connectors (Connector clients) are self-managed on your infrastructure.

application/json

Body

description string
index_name string
is_native boolean
language string
name string
service_type string

Responses

200 application/json
Hide response attributes Show response attributes object
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.
- id string Required

POST /_connector

curl \
 --request POST 'http://api.example.com/_connector' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"description":"string","index_name":"string","is_native":true,"language":"string","name":"string","service_type":"string"}'

Claim a connector sync job Technical preview

PUT /_connector/_sync_job/{connector_sync_job_id}/_claim

Api key auth Basic auth Bearer auth

This action updates the job status to in_progress and sets the last_seen and started_at timestamps to the current time. Additionally, it can set the sync_cursor property for the sync job.

This API is not intended for direct connector management by users. It supports the implementation of services that utilize the connector protocol to communicate with Elasticsearch.

To sync data using self-managed connectors, you need to deploy the Elastic connector service on your own infrastructure. This service runs automatically on Elastic Cloud for Elastic managed connectors.

Path parameters

connector_sync_job_id string Required

The unique identifier of the connector sync job.

application/json

Body Required

sync_cursor object

The cursor object from the last incremental sync job. This should reference the sync_cursor field in the connector state for which the job runs.
worker_hostname string Required

The host name of the current system that will run the job.

Responses

200 application/json

PUT /_connector/_sync_job/{connector_sync_job_id}/_claim

curl \
 --request PUT 'http://api.example.com/_connector/_sync_job/{connector_sync_job_id}/_claim' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"sync_cursor":{},"worker_hostname":"string"}'

Delete a connector sync job Beta

DELETE /_connector/_sync_job/{connector_sync_job_id}

Api key auth Basic auth Bearer auth

Remove a connector sync job and its associated data. This is a destructive action that is not recoverable.

Path parameters

connector_sync_job_id string Required

The unique identifier of the connector sync job 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 /_connector/_sync_job/{connector_sync_job_id}

curl \
 --request DELETE 'http://api.example.com/_connector/_sync_job/{connector_sync_job_id}' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "acknowledged": true
}

Update the connector API key ID Beta

PUT /_connector/{connector_id}/_api_key_id

Api key auth Basic auth Bearer auth

Update the api_key_id and api_key_secret_id fields of a connector. You can specify the ID of the API key used for authorization and the ID of the connector secret where the API key is stored. The connector secret ID is required only for Elastic managed (native) connectors. Self-managed connectors (connector clients) do not use this field.

Path parameters

connector_id string Required

The unique identifier of the connector to be updated

application/json

Body Required

api_key_id string
api_key_secret_id string

Responses

200 application/json
Hide response attribute Show response attribute object
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.

PUT /_connector/{connector_id}/_api_key_id

curl \
 --request PUT 'http://api.example.com/_connector/{connector_id}/_api_key_id' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n    \"api_key_id\": \"my-api-key-id\",\n    \"api_key_secret_id\": \"my-connector-secret-id\"\n}"'

Request example

{
    "api_key_id": "my-api-key-id",
    "api_key_secret_id": "my-connector-secret-id"
}

Response examples (200)

{
  "result": "updated"
}

Update the connector index name Beta

PUT /_connector/{connector_id}/_index_name

Api key auth Basic auth Bearer auth

Update the index_name field of a connector, specifying the index where the data ingested by the connector is stored.

Path parameters

connector_id string Required

The unique identifier of the connector to be updated

application/json

Body Required

index_name string | null

One of:
IndexName string NullValue string | null

Responses

200 application/json
Hide response attribute Show response attribute object
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.

PUT /_connector/{connector_id}/_index_name

curl \
 --request PUT 'http://api.example.com/_connector/{connector_id}/_index_name' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n    \"index_name\": \"data-from-my-google-drive\"\n}"'

Request example

{
    "index_name": "data-from-my-google-drive"
}

Response examples (200)

{
  "result": "updated"
}

Update the connector is_native flag Beta

PUT /_connector/{connector_id}/_native

Api key auth Basic auth Bearer auth

Path parameters

connector_id string Required

The unique identifier of the connector to be updated

application/json

Body Required

is_native boolean Required

Responses

200 application/json
Hide response attribute Show response attribute object
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.

PUT /_connector/{connector_id}/_native

curl \
 --request PUT 'http://api.example.com/_connector/{connector_id}/_native' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"is_native":true}'

Update data stream lifecycles Added in 8.11.0

PUT /_data_stream/{name}/_lifecycle

Api key auth Basic auth Bearer auth

Update the data stream lifecycle of the specified data streams.

Path parameters

name string | array[string] Required

Comma-separated list of data streams used to limit the request. Supports wildcards (*). To target all data streams use * or _all.

Query parameters

expand_wildcards string | array[string]

Type of data stream that wildcard patterns can match. Supports comma-separated values, such as open,hidden. Valid values are: all, hidden, open, closed, none.
master_timeout string

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

data_retention 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.
downsampling object
Hide downsampling attribute Show downsampling attribute object
- rounds array[object] Required
  
  The list of downsampling rounds to execute as part of this downsampling configuration
  Hide rounds attributes Show rounds attributes object
  
  after string Required
  
  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.
  
  config object Required
  
  Hide config attribute Show config attribute object
  
  fixed_interval string Required
  
  A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)
enabled boolean

If defined, it turns data stream lifecycle on/off (true/false) for this data stream. A data stream lifecycle that's disabled (enabled: false) will have no effect on the data stream.

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 /_data_stream/{name}/_lifecycle

curl \
 --request PUT 'http://api.example.com/_data_stream/{name}/_lifecycle' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"data_retention\": \"7d\"\n}"'

Request examples

{
  "data_retention": "7d"
}

This example configures two downsampling rounds.

{
    "downsampling": [
      {
        "after": "1d",
        "fixed_interval": "10m"
      },
      {
        "after": "7d",
        "fixed_interval": "1d"
      }
    ]
}

Response examples (200)

A successful response for configuring a data stream lifecycle.

{
  "acknowledged": true
}

Downsample an index Technical preview

POST /{index}/_downsample/{target_index}

Api key auth Basic auth Bearer auth

Aggregate a time series (TSDS) index and store pre-computed statistical summaries (min, max, sum, value_count and avg) for each metric field grouped by a configured time interval. For example, a TSDS index that contains metrics sampled every 10 seconds can be downsampled to an hourly index. All documents within an hour interval are summarized and stored as a single document in the downsample index.

NOTE: Only indices in a time series data stream are supported. Neither field nor document level security can be defined on the source index. The source index must be read only (index.blocks.write: true).

Path parameters

index string Required

Name of the time series index to downsample.
target_index string Required

Name of the index to create.

application/json

Body Required

fixed_interval string Required

A date histogram interval. Similar to Duration with additional units: w (week), M (month), q (quarter) and y (year)

Responses

200 application/json

POST /{index}/_downsample/{target_index}

curl \
 --request POST 'http://api.example.com/{index}/_downsample/{target_index}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"fixed_interval\": \"1d\"\n}"'

Request example

{
  "fixed_interval": "1d"
}

Convert an index alias to a data stream Added in 7.9.0

POST /_data_stream/_migrate/{name}

Api key auth Basic auth Bearer auth

Converts an index alias to a data stream. You must have a matching index template that is data stream enabled. The alias must meet the following criteria: The alias must have a write index; All indices for the alias must have a @timestamp field mapping of a date or date_nanos field type; The alias must not have any filters; The alias must not use custom routing. If successful, the request removes the alias and creates a data stream with the same name. The indices for the alias become hidden backing indices for the stream. The write index for the alias becomes the write index for the stream.

Path parameters

name string Required

Name of the index alias to convert to a data stream.

Query parameters

master_timeout string

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.

POST /_data_stream/_migrate/{name}

curl \
 --request POST 'http://api.example.com/_data_stream/_migrate/{name}' \
 --header "Authorization: $API_KEY"

Get enrich stats Added in 7.5.0

GET /_enrich/_stats

Api key auth Basic auth Bearer auth

Returns enrich coordinator statistics and information about enrich policies that are currently executing.

Query parameters

master_timeout string

Period to wait for a connection to the master node.

Responses

200 application/json
Hide response attributes Show response attributes object
- coordinator_stats array[object] Required
  
  Objects containing information about each coordinating ingest node for configured enrich processors.
  
  Hide coordinator_stats attributes Show coordinator_stats attributes object
  
  executed_searches_total number Required
  
  node_id string Required
  
  queue_size number Required
  
  remote_requests_current number Required
  
  remote_requests_total number Required
- executing_policies array[object] Required
  
  Objects containing information about each enrich policy that is currently executing.
  
  Hide executing_policies attributes Show executing_policies attributes object
  
  name string Required
  
  task object Required Additional properties
  
  Hide task attributes Show task attributes object
  
  action string Required
  
  cancelled boolean
  
  cancellable boolean Required
  
  description string
  
  Human readable text that identifies the particular request that the task is performing. For example, it might identify the search request being performed by a search task. Other kinds of tasks have different descriptions, like _reindex which has the source and the destination, or _bulk which just has the number of requests and the destination indices. Many requests will have only an empty description because more detailed information about the request is not easily available or particularly helpful in identifying the request.
  
  headers object Required
  
  Hide headers attribute Show headers attribute object
  
  * string Additional properties
  
  id number Required
  
  node string Required
  
  running_time 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.
  
  running_time_in_nanos number
  
  Time unit for nanoseconds
  
  start_time_in_millis number
  
  Time unit for milliseconds
  
  status object
  
  The internal status of the task, which varies from task to task. The format also varies. While the goal is to keep the status for a particular task consistent from version to version, this is not always possible because sometimes the implementation changes. Fields might be removed from the status for a particular request so any parsing you do of the status might break in minor releases.
  
  type string Required
  
  parent_task_id string | number
  
  One of:
  TaskId string TaskId number
- cache_stats array[object]
  
  Objects containing information about the enrich cache stats on each ingest node.
  
  Hide cache_stats attributes Show cache_stats attributes object
  
  node_id string Required
  
  count number Required
  
  hits number Required
  
  hits_time_in_millis number
  
  Time unit for milliseconds
  
  misses number Required
  
  misses_time_in_millis number
  
  Time unit for milliseconds
  
  evictions number Required
  
  size_in_bytes number Required

GET /_enrich/_stats

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

Stop async ES|QL query Added in 8.18.0

POST /_query/async/{id}/stop

Api key auth Basic auth Bearer auth

This API interrupts the query execution and returns the results so far. If the Elasticsearch security features are enabled, only the user who first submitted the ES|QL query can stop it.

External documentation

Path parameters

id string Required

The unique identifier of the query. A query ID is provided in the ES|QL async query API response for a query that does not complete in the designated time. A query ID is also provided when the request was submitted with the keep_on_completion parameter set to true.

Query parameters

drop_null_columns boolean

Indicates whether columns that are entirely null will be removed from the columns and values portion of the results. If true, the response will include an extra section under the name all_columns which has the name of all the columns.

Responses

200 application/json

POST /_query/async/{id}/stop

curl \
 --request POST 'http://api.example.com/_query/async/{id}/stop' \
 --header "Authorization: $API_KEY"

Get global checkpoints Added in 7.13.0

GET /{index}/_fleet/global_checkpoints

Api key auth Basic auth Bearer auth

Get the current global checkpoints for an index. This API is designed for internal use by the Fleet server project.

Path parameters

index string Required

A single index or index alias that resolves to a single index.

Query parameters

wait_for_advance boolean

A boolean value which controls whether to wait (until the timeout) for the global checkpoints to advance past the provided checkpoints.
wait_for_index boolean

A boolean value which controls whether to wait (until the timeout) for the target index to exist and all primary shards be active. Can only be true when wait_for_advance is true.
checkpoints array[number]

A comma separated list of previous global checkpoints. When used in combination with wait_for_advance, the API will only return once the global checkpoints advances past the checkpoints. Providing an empty list will cause Elasticsearch to immediately return the current global checkpoints.
timeout string

Period to wait for a global checkpoints to advance past checkpoints.

Responses

200 application/json
Hide response attributes Show response attributes object
- global_checkpoints array[number] Required
- timed_out boolean Required

GET /{index}/_fleet/global_checkpoints

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

Delete a dangling index Added in 7.9.0

DELETE /_dangling/{index_uuid}

Api key auth Basic auth Bearer auth

If Elasticsearch encounters index data that is absent from the current cluster state, those indices are considered to be dangling. For example, this can happen if you delete more than cluster.indices.tombstones.size indices while an Elasticsearch node is offline.

Path parameters

index_uuid string Required

The UUID of the index to delete. Use the get dangling indices API to find the UUID.

Query parameters

accept_data_loss boolean Required

This parameter must be set to true to acknowledge that it will no longer be possible to recove data from the dangling index.
master_timeout string

Specify timeout for connection to master
timeout string

Explicit operation timeout

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 /_dangling/{index_uuid}

curl \
 --request DELETE 'http://api.example.com/_dangling/{index_uuid}?accept_data_loss=true' \
 --header "Authorization: $API_KEY"

Get the dangling indices Added in 7.9.0

GET /_dangling

Api key auth Basic auth Bearer auth

If Elasticsearch encounters index data that is absent from the current cluster state, those indices are considered to be dangling. For example, this can happen if you delete more than cluster.indices.tombstones.size indices while an Elasticsearch node is offline.

Use this API to list dangling indices, which you can then import or delete.

Responses

200 application/json
Hide response attribute Show response attribute object
- dangling_indices array[object] Required
  
  Hide dangling_indices attributes Show dangling_indices attributes object
  
  index_name string Required
  
  index_uuid string Required
  
  creation_date_millis number
  
  Time unit for milliseconds
  
  node_ids string | array[string] Required
  
  One of:
  Id string Ids array[string]

GET /_dangling

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

Response examples (200)

{
  "dangling_indices": [
   {
    "index_name": "my-index-000001",
    "index_uuid": "zmM4e0JtBkeUjiHD-MihPQ",
    "creation_date_millis": 1589414451372,
    "node_ids": [
      "pL47UN3dAb2d5RCWP6lQ3e"
    ]
   }
  ]
}

Clone an index Added in 7.4.0

POST /{index}/_clone/{target}

Api key auth Basic auth Bearer auth

Clone an existing index into a new index. Each original primary shard is cloned into a new primary shard in the new index.

IMPORTANT: Elasticsearch does not apply index templates to the resulting index. The API also does not copy index metadata from the original index. Index metadata includes aliases, index lifecycle management phase definitions, and cross-cluster replication (CCR) follower information. For example, if you clone a CCR follower index, the resulting clone will not be a follower index.

The clone API copies most index settings from the source index to the resulting index, with the exception of index.number_of_replicas and index.auto_expand_replicas. To set the number of replicas in the resulting index, configure these settings in the clone request.

Cloning works as follows:

First, it creates a new target index with the same definition as the source index.
Then it hard-links segments from the source index into the target index. If the file system does not support hard-linking, all segments are copied into the new index, which is a much more time consuming process.
Finally, it recovers the target index as though it were a closed index which had just been re-opened.

IMPORTANT: Indices can only be cloned if they meet the following requirements:

The index must be marked as read-only and have a cluster health status of green.
The target index must not exist.
The source index must have the same number of primary shards as the target index.
The node handling the clone process must have sufficient free disk space to accommodate a second copy of the existing index.

The current write index on a data stream cannot be cloned. In order to clone the current write index, the data stream must first be rolled over so that a new write index is created and then the previous write index can be cloned.

NOTE: Mappings cannot be specified in the _clone request. The mappings of the source index will be used for the target index.

Monitor the cloning process

The cloning process can be monitored with the cat recovery API or the cluster health API can be used to wait until all primary shards have been allocated by setting the wait_for_status parameter to yellow.

The _clone API returns as soon as the target index has been added to the cluster state, before any shards have been allocated. At this point, all shards are in the state unassigned. If, for any reason, the target index can't be allocated, its primary shard will remain unassigned until it can be allocated on that node.

Once the primary shard is allocated, it moves to state initializing, and the clone process begins. When the clone operation completes, the shard will become active. At that point, Elasticsearch will try to allocate any replicas and may decide to relocate the primary shard to another node.

Wait for active shards

Because the clone operation creates a new index to clone the shards to, the wait for active shards setting on index creation applies to the clone index action as well.

Path parameters

index string Required

Name of the source index to clone.
target string Required

Name of the target index to create.

Query parameters

master_timeout string

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

The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).

application/json

Body

aliases object

Aliases for the resulting index.
Hide aliases attribute Show aliases attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  index_routing string
  
  is_hidden boolean
  
  If true, the alias is hidden. All indices for the alias must have the same is_hidden value.
  
  is_write_index boolean
  
  If true, the index is the write index for the alias.
  
  routing string
  
  search_routing string
settings object

Configuration options for the target index.
Hide settings attribute Show settings attribute object
- * object Additional properties

Responses

200 application/json
Hide response attributes Show response attributes object
- acknowledged boolean Required
- index string Required
- shards_acknowledged boolean Required

POST /{index}/_clone/{target}

curl \
 --request POST 'http://api.example.com/{index}/_clone/{target}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"settings\": {\n    \"index.number_of_shards\": 5\n  },\n  \"aliases\": {\n    \"my_search_indices\": {}\n  }\n}"'

Request example

Clone `my_source_index` into a new index called `my_target_index` with `POST /my_source_index/_clone/my_target_index`. The API accepts `settings` and `aliases` parameters for the target index.

{
  "settings": {
    "index.number_of_shards": 5
  },
  "aliases": {
    "my_search_indices": {}
  }
}

Delete indices

DELETE /{index}

Api key auth Basic auth Bearer auth

Deleting an index deletes its documents, shards, and metadata. It does not delete related Kibana components, such as data views, visualizations, or dashboards.

You cannot delete the current write index of a data stream. To delete the index, you must roll over the data stream so a new write index is created. You can then use the delete index API to delete the previous write index.

Path parameters

index string | array[string] Required

Comma-separated list of indices to delete. You cannot specify index aliases. By default, this parameter does not support wildcards (*) or _all. To use wildcards or _all, set the action.destructive_requires_name cluster setting to false.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.
expand_wildcards string | array[string]

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. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
master_timeout string

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 attributes Show response attributes object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.
- _shards object
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number

DELETE /{index}

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

Get aliases

GET /{index}/_alias/{name}

Api key auth Basic auth Bearer auth

Retrieves information for one or more data stream or index aliases.

Path parameters

index string | array[string] Required

Comma-separated list of data streams or indices used to limit the request. Supports wildcards (*). To target all data streams and indices, omit this parameter or use * or _all.
name string | array[string] Required

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

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.
expand_wildcards string | array[string]

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. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
local boolean Deprecated

If true, the request retrieves information from the local node only.

Responses

200 application/json
Hide response attribute Show response attribute object
- * object Additional properties
  
  Hide * attribute Show * attribute object
  
  aliases object Required
  
  Hide aliases attribute Show aliases attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  index_routing string
  
  Value used to route indexing operations to a specific shard. If specified, this overwrites the routing value for indexing operations.
  
  is_write_index boolean
  
  If true, the index is the write index for the alias.
  
  routing string
  
  Value used to route indexing and search operations to a specific shard.
  
  search_routing string
  
  Value used to route search operations to a specific shard. If specified, this overwrites the routing value for search operations.
  
  is_hidden boolean
  
  If true, the alias is hidden. All indices for the alias must have the same is_hidden value.

GET /{index}/_alias/{name}

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

Create or update an alias

POST /{index}/_alias/{name}

Api key auth Basic auth Bearer auth

Adds a data stream or index to an alias.

Path parameters

index string | array[string] Required

Comma-separated list of data streams or indices to add. Supports wildcards (*). Wildcard patterns that match both data streams and indices return an error.
name string Required

Alias to update. If the alias doesn’t exist, the request creates it. Index alias names support date math.

Query parameters

master_timeout string

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

filter object

An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.

External documentation
index_routing string
is_write_index boolean

If true, sets the write index or data stream for the alias. If an alias points to multiple indices or data streams and is_write_index isn’t set, the alias rejects write requests. If an index alias points to one index and is_write_index isn’t set, the index automatically acts as the write index. Data stream aliases don’t automatically set a write data stream, even if the alias points to one data stream.
routing string
search_routing string

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.

POST /{index}/_alias/{name}

curl \
 --request POST 'http://api.example.com/{index}/_alias/{name}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"actions\": [\n    {\n      \"add\": {\n        \"index\": \"my-data-stream\",\n        \"alias\": \"my-alias\"\n      }\n    }\n  ]\n}"'

Request example

{
  "actions": [
    {
      "add": {
        "index": "my-data-stream",
        "alias": "my-alias"
      }
    }
  ]
}

Delete an alias

DELETE /{index}/_aliases/{name}

Api key auth Basic auth Bearer auth

Removes a data stream or index from an alias.

Path parameters

index string | array[string] Required

Comma-separated list of data streams or indices used to limit the request. Supports wildcards (*).
name string | array[string] Required

Comma-separated list of aliases to remove. Supports wildcards (*). To remove all aliases, use * or _all.

Query parameters

master_timeout string

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 /{index}/_aliases/{name}

curl \
 --request DELETE 'http://api.example.com/{index}/_aliases/{name}' \
 --header "Authorization: $API_KEY"

Check index templates

HEAD /_index_template/{name}

Api key auth Basic auth Bearer auth

Check whether index templates exist.

Path parameters

name string Required

Comma-separated list of index template names used to limit the request. Wildcard (*) expressions are supported.

Query parameters

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.
flat_settings boolean

If true, returns settings in flat format.
master_timeout string

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

HEAD /_index_template/{name}

curl \
 --request HEAD 'http://api.example.com/_index_template/{name}' \
 --header "Authorization: $API_KEY"

Check existence of index templates

HEAD /_template/{name}

Api key auth Basic auth Bearer auth

Get information about whether index templates exist. Index templates define settings, mappings, and aliases that can be applied automatically to new indices.

IMPORTANT: This documentation is about legacy index templates, which are deprecated and will be replaced by the composable templates introduced in Elasticsearch 7.8.

External documentation

Path parameters

name string | array[string] Required

A comma-separated list of index template names used to limit the request. Wildcard (*) expressions are supported.

Query parameters

flat_settings boolean

Indicates whether to use a flat format for the response.
local boolean

Indicates whether to get information from the local node only.
master_timeout string

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

Responses

200 application/json

HEAD /_template/{name}

curl \
 --request HEAD 'http://api.example.com/_template/{name}' \
 --header "Authorization: $API_KEY"

Flush data streams or indices

POST /{index}/_flush

Api key auth Basic auth Bearer auth

Flushing a data stream or index is the process of making sure that any data that is currently only stored in the transaction log is also permanently stored in the Lucene index. When restarting, Elasticsearch replays any unflushed operations from the transaction log into the Lucene index to bring it back into the state that it was in before the restart. Elasticsearch automatically triggers flushes as needed, using heuristics that trade off the size of the unflushed transaction log against the cost of performing each flush.

After each operation has been flushed it is permanently stored in the Lucene index. This may mean that there is no need to maintain an additional copy of it in the transaction log. The transaction log is made up of multiple files, called generations, and Elasticsearch will delete any generation files when they are no longer needed, freeing up disk space.

It is also possible to trigger a flush on one or more indices using the flush API, although it is rare for users to need to call this API directly. If you call the flush API after indexing some documents then a successful response indicates that Elasticsearch has flushed all the documents that were indexed before the flush API was called.

Path parameters

index string | array[string] Required

Comma-separated list of data streams, indices, and aliases to flush. Supports wildcards (*). To flush all data streams and indices, omit this parameter or use * or _all.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.
expand_wildcards string | array[string]

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. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.
force boolean

If true, the request forces a flush even if there are no changes to commit to the index.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
wait_if_ongoing boolean

If true, the flush operation blocks until execution when another flush operation is running. If false, Elasticsearch returns an error if you request a flush when another flush operation is running.

Responses

200 application/json
Hide response attribute Show response attribute object
- _shards object
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number

POST /{index}/_flush

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

Get aliases

GET /{index}/_alias

Api key auth Basic auth Bearer auth

Retrieves information for one or more data stream or index aliases.

Path parameters

index string | array[string] Required

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

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.
expand_wildcards string | array[string]

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. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
local boolean Deprecated

If true, the request retrieves information from the local node only.

Responses

200 application/json
Hide response attribute Show response attribute object
- * object Additional properties
  
  Hide * attribute Show * attribute object
  
  aliases object Required
  
  Hide aliases attribute Show aliases attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  index_routing string
  
  Value used to route indexing operations to a specific shard. If specified, this overwrites the routing value for indexing operations.
  
  is_write_index boolean
  
  If true, the index is the write index for the alias.
  
  routing string
  
  Value used to route indexing and search operations to a specific shard.
  
  search_routing string
  
  Value used to route search operations to a specific shard. If specified, this overwrites the routing value for search operations.
  
  is_hidden boolean
  
  If true, the alias is hidden. All indices for the alias must have the same is_hidden value.

GET /{index}/_alias

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

Get mapping definitions

GET /_mapping/field/{fields}

Api key auth Basic auth Bearer auth

Retrieves mapping definitions for one or more fields. For data streams, the API retrieves field mappings for the stream’s backing indices.

This API is useful if you don't need a complete mapping or if an index mapping contains a large number of fields.

Path parameters

fields string | array[string] Required

Comma-separated list or wildcard expression of fields used to limit returned information. Supports wildcards (*).

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.
expand_wildcards string | array[string]

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. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
include_defaults boolean

If true, return all default settings in the response.
local boolean

If true, the request retrieves information from the local node only.

Responses

200 application/json
Hide response attribute Show response attribute object
- * object Additional properties
  
  Hide * attribute Show * attribute object
  
  mappings object Required
  
  Hide mappings attribute Show mappings attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  full_name string Required
  
  mapping object Required

GET /_mapping/field/{fields}

curl \
 --request GET 'http://api.example.com/_mapping/field/{fields}' \
 --header "Authorization: $API_KEY"

Response examples (200)

A sucessful response from `GET publications/_mapping/field/title`, which returns the mapping of a field called `title`.

{
   "publications": {
      "mappings": {
          "title": {
             "full_name": "title",
             "mapping": {
                "title": {
                   "type": "text"
                }
             }
          }
       }
   }
}

A successful response from `GET publications/_mapping/field/author.id,abstract,name`. The get field mapping API also supports wildcard notation.

{
   "publications": {
      "mappings": {
        "author.id": {
           "full_name": "author.id",
           "mapping": {
              "id": {
                 "type": "text"
              }
           }
        },
        "abstract": {
           "full_name": "abstract",
           "mapping": {
              "abstract": {
                 "type": "text"
              }
           }
        }
     }
   }
}

A successful response from `GET publications/_mapping/field/a*`.

{
   "publications": {
      "mappings": {
         "author.name": {
            "full_name": "author.name",
            "mapping": {
               "name": {
                 "type": "text"
               }
            }
         },
         "abstract": {
            "full_name": "abstract",
            "mapping": {
               "abstract": {
                  "type": "text"
               }
            }
         },
         "author.id": {
            "full_name": "author.id",
            "mapping": {
               "id": {
                  "type": "text"
               }
            }
         }
      }
   }
}

Open a closed index

POST /{index}/_open

Api key auth Basic auth Bearer auth

For data streams, the API opens any closed backing indices.

A closed index is blocked for read/write operations and does not allow all operations that opened indices allow. It is not possible to index documents or to search for documents in a closed index. This allows closed indices to not have to maintain internal data structures for indexing or searching documents, resulting in a smaller overhead on the cluster.

When opening or closing an index, the master is responsible for restarting the index shards to reflect the new state of the index. The shards will then go through the normal recovery process. The data of opened or closed indices is automatically replicated by the cluster to ensure that enough shard copies are safely kept around at all times.

You can open and close multiple indices. An error is thrown if the request explicitly refers to a missing index. This behavior can be turned off by using the ignore_unavailable=true parameter.

By default, you must explicitly name the indices you are opening or closing. To open or close indices with _all, *, or other wildcard expressions, change the action.destructive_requires_name setting to false. This setting can also be changed with the cluster update settings API.

Closed indices consume a significant amount of disk-space which can cause problems in managed environments. Closing indices can be turned off with the cluster settings API by setting cluster.indices.close.enable to false.

Because opening or closing an index allocates its shards, the wait_for_active_shards setting on index creation applies to the _open and _close index actions as well.

Path parameters

index string | array[string] Required

Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (*). By default, you must explicitly name the indices you using to limit the request. To limit a request using _all, *, or other wildcard expressions, change the action.destructive_requires_name setting to false. You can update this setting in the elasticsearch.yml file or using the cluster update settings API.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.
expand_wildcards string | array[string]

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. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
master_timeout string

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

The number of shard copies that must be active before proceeding with the operation. Set to all or any positive integer up to the total number of shards in the index (number_of_replicas+1).

Responses

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

POST /{index}/_open

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

Response examples (200)

A successful response for opening an index.

{
  "acknowledged" : true,
  "shards_acknowledged" : true
}

Refresh an index

POST /_refresh

Api key auth Basic auth Bearer auth

A refresh makes recent operations performed on one or more indices available for search. For data streams, the API runs the refresh operation on the stream’s backing indices.

By default, Elasticsearch periodically refreshes indices every second, but only on indices that have received one search request or more in the last 30 seconds. You can change this default interval with the index.refresh_interval setting.

Refresh requests are synchronous and do not return a response until the refresh operation completes.

Refreshes are resource-intensive. To ensure good cluster performance, it's recommended to wait for Elasticsearch's periodic refresh rather than performing an explicit refresh when possible.

If your application workflow indexes documents and then runs a search to retrieve the indexed document, it's recommended to use the index API's refresh=wait_for query parameter option. This option ensures the indexing operation waits for a periodic refresh before running the search.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.
expand_wildcards string | array[string]

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. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.

Responses

200 application/json
Hide response attribute Show response attribute object
- _shards object
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number

POST /_refresh

curl \
 --request POST 'http://api.example.com/_refresh' \
 --header "Authorization: $API_KEY"

Reload search analyzers Added in 7.3.0

POST /{index}/_reload_search_analyzers

Api key auth Basic auth Bearer auth

Reload an index's search analyzers and their resources. For data streams, the API reloads search analyzers and resources for the stream's backing indices.

IMPORTANT: After reloading the search analyzers you should clear the request cache to make sure it doesn't contain responses derived from the previous versions of the analyzer.

You can use the reload search analyzers API to pick up changes to synonym files used in the synonym_graph or synonym token filter of a search analyzer. To be eligible, the token filter must have an updateable flag of true and only be used in search analyzers.

NOTE: This API does not perform a reload for each shard of an index. Instead, it performs a reload for each node containing index shards. As a result, the total shard count returned by the API can differ from the number of index shards. Because reloading affects every node with an index shard, it is important to update the synonym file on every data node in the cluster--including nodes that don't contain a shard replica--before using this API. This ensures the synonym file is updated everywhere in the cluster in case shards are relocated in the future.

External documentation

Path parameters

index string | array[string] Required

A comma-separated list of index names to reload analyzers for

Query parameters

allow_no_indices boolean

Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes _all string or when no indices have been specified)
expand_wildcards string | array[string]

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

Whether specified concrete indices should be ignored when unavailable (missing or closed)
resource string

Changed resource to reload analyzers from if applicable

Responses

200 application/json
Hide response attributes Show response attributes object
- reload_details array[object] Required
  
  Hide reload_details attributes Show reload_details attributes object
  
  index string Required
  
  reloaded_analyzers array[string] Required
  
  reloaded_node_ids array[string] Required
- _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number

POST /{index}/_reload_search_analyzers

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

Get index segments

GET /{index}/_segments

Api key auth Basic auth Bearer auth

Get low-level information about the Lucene segments in index shards. For data streams, the API returns information about the stream's backing indices.

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

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.
expand_wildcards string | array[string]

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. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index.
verbose boolean

If true, the request returns a verbose response.

Responses

200 application/json
Hide response attributes Show response attributes object
- indices object Required
  
  Hide indices attribute Show indices attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  shards object Required
- _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number

GET /{index}/_segments

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

Response examples (200)

A successful response for creating a new index for a data stream.

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "old_index": ".ds-my-data-stream-2099.05.06-000001",
  "new_index": ".ds-my-data-stream-2099.05.07-000002",
  "rolled_over": true,
  "dry_run": false,
  "lazy": false,
  "conditions": {
    "[max_age: 7d]": false,
    "[max_docs: 1000]": true,
    "[max_primary_shard_size: 50gb]": false,
    "[max_primary_shard_docs: 2000]": false
  }
}

Simulate an index Added in 7.9.0

POST /_index_template/_simulate_index/{name}

Api key auth Basic auth Bearer auth

Get the index configuration that would be applied to the specified index from an existing index template.

Path parameters

name string Required

Name of the index to simulate

Query parameters

create boolean

Whether the index template we optionally defined in the body should only be dry-run added if new or can also replace an existing one
cause string

User defined reason for dry-run creating the new template for simulation purposes
master_timeout string

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.
include_defaults boolean

If true, returns all relevant default configurations for the index template.

Responses

200 application/json
Hide response attributes Show response attributes object
- overlapping array[object]
  
  Hide overlapping attributes Show overlapping attributes object
  
  name string Required
  
  index_patterns array[string] Required
- template object Required
  
  Hide template attributes Show template attributes object
  
  aliases object Required
  
  Hide aliases attribute Show aliases attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  index_routing string
  
  is_hidden boolean
  
  If true, the alias is hidden. All indices for the alias must have the same is_hidden value.
  
  is_write_index boolean
  
  If true, the index is the write index for the alias.
  
  routing string
  
  search_routing string
  
  mappings object Required
  
  Hide mappings attributes Show mappings attributes object
  
  all_field object
  
  Hide all_field attributes Show all_field attributes object
  
  analyzer string Required
  
  enabled boolean Required
  
  omit_norms boolean Required
  
  search_analyzer string Required
  
  similarity string Required
  
  store boolean Required
  
  store_term_vector_offsets boolean Required
  
  store_term_vector_payloads boolean Required
  
  store_term_vector_positions boolean Required
  
  store_term_vectors boolean Required
  
  date_detection boolean
  
  dynamic string
  
  Values are strict, runtime, true, or false.
  
  dynamic_date_formats array[string]
  
  dynamic_templates array[object]
  
  _field_names object
  
  Hide _field_names attribute Show _field_names attribute object
  
  enabled boolean Required
  
  index_field object
  
  Hide index_field attribute Show index_field attribute object
  
  enabled boolean Required
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
  
  numeric_detection boolean
  
  properties object
  
  _routing object
  
  Hide _routing attribute Show _routing attribute object
  
  required boolean Required
  
  _size object
  
  Hide _size attribute Show _size attribute object
  
  enabled boolean Required
  
  _source object
  
  Hide _source attributes Show _source attributes object
  
  compress boolean
  
  compress_threshold string
  
  enabled boolean
  
  excludes array[string]
  
  includes array[string]
  
  mode string
  
  Values are disabled, stored, or synthetic.
  
  runtime object
  
  Hide runtime attribute Show runtime attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  fetch_fields array[object]
  
  For type lookup
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string
  
  The script source.
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  lang
  
  options object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  enabled boolean
  
  subobjects string
  
  Values are true or false.
  
  _data_stream_timestamp object
  
  Hide _data_stream_timestamp attribute Show _data_stream_timestamp attribute object
  
  enabled boolean Required
  
  settings object Required
  
  Hide settings attributes Show settings attributes object
  
  index object
  
  mode string
  
  routing_path string | array[string]
  
  One of:
  string-1 string array-2 array[string]
  
  soft_deletes object
  
  Hide soft_deletes attributes Show soft_deletes attributes object
  
  enabled boolean
  
  Indicates whether soft deletes are enabled on the index.
  
  retention_lease object
  
  Hide retention_lease attribute Show retention_lease attribute object
  
  period string Required
  
  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.
  
  sort object
  
  Hide sort attributes Show sort attributes object
  
  field string | array[string]
  
  order string | array[string]
  
  One of:
  SegmentSortOrder string array-2 array[string]
  
  Values are asc, ASC, desc, or DESC.
  
  mode string | array[string]
  
  One of:
  SegmentSortMode string array-2 array[string]
  
  Values are min, MIN, max, or MAX.
  
  missing string | array[string]
  
  One of:
  SegmentSortMissing string array-2 array[string]
  
  Values are _last or _first.
  
  number_of_shards number | string
  
  One of:
  number-1 number string-2 string
  
  number_of_replicas number | string
  
  One of:
  number-1 number string-2 string
  
  number_of_routing_shards number
  
  check_on_startup string
  
  Values are true, false, or checksum.
  
  codec string
  
  routing_partition_size number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedinteger number Stringifiedinteger string
  
  load_fixed_bitset_filters_eagerly boolean
  
  hidden boolean | string
  
  One of:
  boolean-1 boolean string-2 string
  
  auto_expand_replicas string | null
  
  One of:
  string-1 string NullValue string | null
  
  merge object
  
  Hide merge attribute Show merge attribute object
  
  scheduler object
  
  Hide scheduler attributes Show scheduler attributes object
  
  max_thread_count number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedinteger number Stringifiedinteger string
  
  max_merge_count number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedinteger number Stringifiedinteger string
  
  search object
  
  Hide search attributes Show search attributes object
  
  idle object
  
  Hide idle attribute Show idle attribute object
  
  after 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.
  
  slowlog object
  
  Hide slowlog attributes Show slowlog attributes object
  
  level string
  
  source number
  
  reformat boolean
  
  threshold object
  
  Hide threshold attributes Show threshold attributes object
  
  query object
  
  fetch object
  
  refresh_interval 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.
  
  max_result_window number
  
  max_inner_result_window number
  
  max_rescore_window number
  
  max_docvalue_fields_search number
  
  max_script_fields number
  
  max_ngram_diff number
  
  max_shingle_diff number
  
  blocks object
  
  Hide blocks attributes Show blocks attributes object
  
  read_only boolean | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  read_only_allow_delete boolean | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  read boolean | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  write boolean | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  metadata boolean | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  max_refresh_listeners number
  
  analyze object
  
  Hide analyze attribute Show analyze attribute object
  
  max_token_count number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedinteger number Stringifiedinteger string
  
  highlight object
  
  Hide highlight attribute Show highlight attribute object
  
  max_analyzed_offset number
  
  max_terms_count number
  
  max_regex_length number
  
  routing object
  
  Hide routing attributes Show routing attributes object
  
  allocation object
  
  Hide allocation attributes Show allocation attributes object
  
  enable string
  
  Values are all, primaries, new_primaries, or none.
  
  include object
  
  Hide include attributes Show include attributes object
  
  _tier_preference string
  
  _id string
  
  initial_recovery object
  
  Hide initial_recovery attribute Show initial_recovery attribute object
  
  _id string
  
  disk object
  
  Hide disk attribute Show disk attribute object
  
  threshold_enabled
  
  rebalance object
  
  Hide rebalance attribute Show rebalance attribute object
  
  enable string Required
  
  Values are all, primaries, replicas, or none.
  
  gc_deletes 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.
  
  default_pipeline string
  
  final_pipeline string
  
  lifecycle object
  
  Hide lifecycle attributes Show lifecycle attributes object
  
  name string
  
  indexing_complete boolean | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  origination_date number
  
  If specified, this is the timestamp used to calculate the index age for its phase transitions. Use this setting if you create a new index that contains old data and want to use the original creation date to calculate the index age. Specified as a Unix epoch value in milliseconds.
  
  parse_origination_date boolean
  
  Set to true to parse the origination date from the index name. This origination date is used to calculate the index age for its phase transitions. The index name must match the pattern ^{.*-{date_format}-\d+,} where the date_format is yyyy.MM.dd and the trailing digits are optional. An index that was rolled over would normally match the full format, for example logs-2016.10.31-000002). If the index name doesn’t match the pattern, index creation fails.
  
  step object
  
  Hide step attribute Show step attribute object
  
  wait_time_threshold 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.
  
  rollover_alias string
  
  The index alias to update when the index rolls over. Specify when using a policy that contains a rollover action. When the index rolls over, the alias is updated to reflect that the index is no longer the write index. For more information about rolling indices, see Rollover.
  
  prefer_ilm boolean | string
  
  Preference for the system that manages a data stream backing index (preferring ILM when both ILM and DLM are applicable for an index).
  
  One of:
  boolean-1 boolean string-2 string
  
  provided_name string
  
  creation_date number | string
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  UnitMillis number StringifiedEpochTimeUnitMillis string
  
  Time unit for milliseconds
  
  creation_date_string string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  uuid string
  
  version object
  
  Hide version attributes Show version attributes object
  
  created string
  
  created_string string
  
  verified_before_close boolean | string
  
  One of:
  boolean-1 boolean string-2 string
  
  format string | number
  
  One of:
  string-1 string number-2 number
  
  max_slices_per_scroll number
  
  translog object
  
  Hide translog attributes Show translog attributes object
  
  sync_interval 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.
  
  durability string
  
  Values are request, REQUEST, async, or ASYNC.
  
  flush_threshold_size number | string
  
  One of:
  ByteSize number ByteSize string
  
  retention object
  
  Hide retention attributes Show retention attributes object
  
  size number | string
  
  One of:
  ByteSize number ByteSize string
  
  age 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.
  
  query_string object
  
  Hide query_string attribute Show query_string attribute object
  
  lenient boolean | string Required
  
  Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior is used to capture this behavior while keeping the semantics of the field type.
  
  Depending on the target language, code generators can keep the union or remove it and leniently parse strings to the target type.
  
  One of:
  Stringifiedboolean boolean Stringifiedboolean string
  
  priority number | string
  
  One of:
  number-1 number string-2 string
  
  top_metrics_max_size number
  
  analysis object
  
  Hide analysis attributes Show analysis attributes object
  
  analyzer object
  
  char_filter object
  
  filter object
  
  normalizer object
  
  tokenizer object
  
  settings object
  
  time_series object
  
  Hide time_series attributes Show time_series attributes object
  
  end_time string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  start_time string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
  
  queries object
  
  Hide queries attribute Show queries attribute object
  
  cache object
  
  Hide cache attribute Show cache attribute object
  
  enabled boolean Required
  
  similarity object
  
  Configure custom similarity settings to customize how search results are scored.
  
  mapping object
  
  Hide mapping attributes Show mapping attributes object
  
  coerce boolean
  
  total_fields object
  
  Hide total_fields attributes Show total_fields attributes object
  
  limit number | string
  
  The maximum number of fields in an index. Field and object mappings, as well as field aliases count towards this limit. The limit is in place to prevent mappings and searches from becoming too large. Higher values can lead to performance degradations and memory issues, especially in clusters with a high load or few resources.
  
  One of:
  number-1 number string-2 string
  
  ignore_dynamic_beyond_limit boolean | string
  
  This setting determines what happens when a dynamically mapped field would exceed the total fields limit. When set to false (the default), the index request of the document that tries to add a dynamic field to the mapping will fail with the message Limit of total fields [X] has been exceeded. When set to true, the index request will not fail. Instead, fields that would exceed the limit are not added to the mapping, similar to dynamic: false. The fields that were not added to the mapping will be added to the _ignored field.
  
  One of:
  boolean-1 boolean string-2 string
  
  depth object
  
  Hide depth attribute Show depth attribute object
  
  limit number
  
  The maximum depth for a field, which is measured as the number of inner objects. For instance, if all fields are defined at the root object level, then the depth is 1. If there is one object mapping, then the depth is 2, etc.
  
  nested_fields object
  
  Hide nested_fields attribute Show nested_fields attribute object
  
  limit number
  
  The maximum number of distinct nested mappings in an index. The nested type should only be used in special cases, when arrays of objects need to be queried independently of each other. To safeguard against poorly designed mappings, this setting limits the number of unique nested types per index.
  
  nested_objects object
  
  Hide nested_objects attribute Show nested_objects attribute object
  
  limit number
  
  The maximum number of nested JSON objects that a single document can contain across all nested types. This limit helps to prevent out of memory errors when a document contains too many nested objects.
  
  field_name_length object
  
  Hide field_name_length attribute Show field_name_length attribute object
  
  limit number
  
  Setting for the maximum length of a field name. This setting isn’t really something that addresses mappings explosion but might still be useful if you want to limit the field length. It usually shouldn’t be necessary to set this setting. The default is okay unless a user starts to add a huge number of fields with really long names. Default is Long.MAX_VALUE (no limit).
  
  dimension_fields object
  
  Hide dimension_fields attribute Show dimension_fields attribute object
  
  limit number
  
  [preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
  
  source object
  
  Hide source attribute Show source attribute object
  
  mode string Required
  
  Values are disabled, stored, or synthetic.
  
  ignore_malformed boolean | string
  
  One of:
  boolean-1 boolean string-2 string
  
  indexing.slowlog object
  
  Hide indexing.slowlog attributes Show indexing.slowlog attributes object
  
  level string
  
  source number
  
  reformat boolean
  
  threshold object
  
  Hide threshold attribute Show threshold attribute object
  
  index object
  
  Hide index attributes Show index attributes object
  
  warn 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.
  
  info 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.
  
  debug 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.
  
  trace 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.
  
  indexing_pressure object
  
  Hide indexing_pressure attribute Show indexing_pressure attribute object
  
  memory object Required
  
  Hide memory attribute Show memory attribute object
  
  limit number
  
  Number of outstanding bytes that may be consumed by indexing requests. When this limit is reached or exceeded, the node will reject new coordinating and primary operations. When replica operations consume 1.5x this limit, the node will reject new replica operations. Defaults to 10% of the heap.
  
  store object
  
  Hide store attributes Show store attributes object
  
  type string Required
  
  Any of:
  StorageType string StorageType string
  
  Values are fs, niofs, mmapfs, or hybridfs.
  
  allow_mmap boolean
  
  You can restrict the use of the mmapfs and the related hybridfs store type via the setting node.store.allow_mmap. This is a boolean setting indicating whether or not memory-mapping is allowed. The default is to allow it. This setting is useful, for example, if you are in an environment where you can not control the ability to create a lot of memory maps so you need disable the ability to use memory-mapping.

POST /_index_template/_simulate_index/{name}

curl \
 --request POST 'http://api.example.com/_index_template/_simulate_index/{name}' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response from `POST /_index_template/_simulate_index/my-index-000001`.

{
  "template" : {
    "settings" : {
      "index" : {
        "number_of_shards" : "2",
        "number_of_replicas" : "0",
        "routing" : {
          "allocation" : {
            "include" : {
              "_tier_preference" : "data_content"
            }
          }
        }
      }
    },
    "mappings" : {
      "properties" : {
        "@timestamp" : {
          "type" : "date"
        }
      }
    },
    "aliases" : { }
  },
  "overlapping" : [
    {
      "name" : "template_1",
      "index_patterns" : [
        "my-index-*"
      ]
    }
  ]
}