Create a behavioral analytics collection Technical preview; Added in 8.8.0

PUT /_application/analytics/{name}

Path parameters

name string Required

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

Responses

200 application/json
Hide response attributes Show response attributes object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.
- name string Required

PUT /_application/analytics/{name}

PUT _application/analytics/my_analytics_collection

resp = client.search_application.put_behavioral_analytics(
    name="my_analytics_collection",
)

const response = await client.searchApplication.putBehavioralAnalytics({
  name: "my_analytics_collection",
});

response = client.search_application.put_behavioral_analytics(
  name: "my_analytics_collection"
)

$resp = $client->searchApplication()->putBehavioralAnalytics([
    "name" => "my_analytics_collection",
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_application/analytics/my_analytics_collection"

client.searchApplication().putBehavioralAnalytics(p -> p
    .name("my_analytics_collection")
);

Compact and aligned text (CAT)

The compact and aligned text (CAT) APIs aim are intended only for human consumption using the Kibana console or command line. They are not intended for use by applications. For application consumption, it's recommend to use a corresponding JSON API. All the cat commands accept a query string parameter help to see all the headers and info they provide, and the /_cat command alone lists all the available commands.

Get the cluster health status Generally available

GET /_cat/health

Api key auth Basic auth Bearer auth

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 cluster health API. This API is often used to check malfunctioning clusters. To help you track cluster health alongside log files and alerting systems, the API returns timestamps in two formats: HH:MM:SS, which is human-readable but includes no date information; Unix epoch time, which is machine-sortable and includes date information. The latter format is useful for cluster recoveries that take multiple days. You can use the cat health API to verify cluster health across multiple nodes. You also can use the API to track the recovery of a large cluster over a longer period of time.

Required authorization

Cluster privileges: monitor

Query parameters

time string

The unit used to display time values.

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

If true, returns HH:MM:SS and Unix epoch timestamps.
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 string-2 string
  
  Time unit for seconds
- timestamp string
  
  Time of day, expressed as HH:MM:SS
- cluster string
  
  cluster name
- status string
  
  health status
- node.total string
  
  total number of nodes
- node.data string
  
  number of nodes that can store data
- shards string
  
  total number of shards
- pri string
  
  number of primary shards
- relo string
  
  number of relocating nodes
- init string
  
  number of initializing nodes
- unassign.pri string
  
  number of unassigned primary shards
- unassign string
  
  number of unassigned shards
- pending_tasks string
  
  number of pending tasks
- max_task_wait_time string
  
  wait time of longest task pending
- active_shards_percent string
  
  active number of shards in percent

GET /_cat/health

GET /_cat/health?v=true&format=json

resp = client.cat.health(
    v=True,
    format="json",
)

const response = await client.cat.health({
  v: "true",
  format: "json",
});

response = client.cat.health(
  v: "true",
  format: "json"
)

$resp = $client->cat()->health([
    "v" => "true",
    "format" => "json",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/health?v=true&format=json"

client.cat().health();

Response examples (200)

A successful response from `GET /_cat/health?v=true&format=json`. By default, it returns `HH:MM:SS` and Unix epoch timestamps.

[
  {
    "epoch": "1475871424",
    "timestamp": "16:17:04",
    "cluster": "elasticsearch",
    "status": "green",
    "node.total": "1",
    "node.data": "1",
    "shards": "1",
    "pri": "1",
    "relo": "0",
    "init": "0",
    "unassign": "0",
    "unassign.pri": "0",
    "pending_tasks": "0",
    "max_task_wait_time": "-",
    "active_shards_percent": "100.0%"
  }
]

Get node information Generally available

GET /_cat/nodes

Api key auth Basic auth Bearer auth

Get information about the nodes in a cluster. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.

Required authorization

Cluster privileges: monitor

Query parameters

bytes string

The unit used to display byte values.

Values are b, kb, mb, gb, tb, or pb.
full_id boolean | string

If true, return the full node ID. If false, return the shortened node ID.
include_unloaded_segments boolean

If true, the response includes information from segments that are not loaded into memory.
h string | array[string]
A comma-separated list of columns names to display. It supports simple wildcards.

Supported values include:
- build (or b): The Elasticsearch build hash. For example: 5c03844.
- completion.size (or cs, completionSize): The size of completion. For example: 0b.
- cpu: The percentage of recent system CPU used.
- disk.avail (or d, disk, diskAvail): The available disk space. For example: 198.4gb.
- disk.total (or dt, diskTotal): The total disk space. For example: 458.3gb.
- disk.used (or du, diskUsed): The used disk space. For example: 259.8gb.
- disk.used_percent (or dup, diskUsedPercent): The percentage of disk space used.
- fielddata.evictions (or fe, fielddataEvictions): The number of fielddata cache evictions.
- fielddata.memory_size (or fm, fielddataMemory): The fielddata cache memory used. For example: 0b.
- file_desc.current (or fdc, fileDescriptorCurrent): The number of file descriptors used.
- file_desc.max (or fdm, fileDescriptorMax): The maximum number of file descriptors.
- file_desc.percent (or fdp, fileDescriptorPercent): The percentage of file descriptors used.
- flush.total (or ft, flushTotal): The number of flushes.
- flush.total_time (or ftt, flushTotalTime): The amount of time spent in flush.
- get.current (or gc, getCurrent): The number of current get operations.
- get.exists_time (or geti, getExistsTime): The time spent in successful get operations. For example: 14ms.
- get.exists_total (or geto, getExistsTotal): The number of successful get operations.
- get.missing_time (or gmti, getMissingTime): The time spent in failed get operations. For example: 0s.
- get.missing_total (or gmto, getMissingTotal): The number of failed get operations.
- get.time (or gti, getTime): The amount of time spent in get operations. For example: 14ms.
- get.total (or gto, getTotal): The number of get operations.
- heap.current (or hc, heapCurrent): The used heap size. For example: 311.2mb.
- heap.max (or hm, heapMax): The total heap size. For example: 4gb.
- heap.percent (or hp, heapPercent): The used percentage of total allocated Elasticsearch JVM heap. This value reflects only the Elasticsearch process running within the operating system and is the most direct indicator of its JVM, heap, or memory resource performance.
- http_address (or http): The bound HTTP address.
- id (or nodeId): The identifier for the node.
- indexing.delete_current (or idc, indexingDeleteCurrent): The number of current deletion operations.
- indexing.delete_time (or idti, indexingDeleteTime): The time spent in deletion operations. For example: 2ms.
- indexing.delete_total (or idto, indexingDeleteTotal): The number of deletion operations.
- indexing.index_current (or iic, indexingIndexCurrent): The number of current indexing operations.
- indexing.index_failed (or iif, indexingIndexFailed): The number of failed indexing operations.
- indexing.index_failed_due_to_version_conflict (or iifvc, indexingIndexFailedDueToVersionConflict): The number of indexing operations that failed due to version conflict.
- indexing.index_time (or iiti, indexingIndexTime): The time spent in indexing operations. For example: 134ms.
- indexing.index_total (or iito, indexingIndexTotal): The number of indexing operations.
- ip (or i): The IP address.
- jdk (or j): The Java version. For example: 1.8.0.
- load_1m (or l): The most recent load average. For example: 0.22.
- load_5m (or l): The load average for the last five minutes. For example: 0.78.
- load_15m (or l): The load average for the last fifteen minutes. For example: 1.24.
- mappings.total_count (or mtc, mappingsTotalCount): The number of mappings, including runtime and object fields.
- mappings.total_estimated_overhead_in_bytes (or mteo, mappingsTotalEstimatedOverheadInBytes): The estimated heap overhead, in bytes, of mappings on this node, which allows for 1KiB of heap for every mapped field.
- master (or m): Indicates whether the node is the elected master node. Returned values include * (elected master) and - (not elected master).
- merges.current (or mc, mergesCurrent): The number of current merge operations.
- merges.current_docs (or mcd, mergesCurrentDocs): The number of current merging documents.
- merges.current_size (or mcs, mergesCurrentSize): The size of current merges. For example: 0b.
- merges.total (or mt, mergesTotal): The number of completed merge operations.
- merges.total_docs (or mtd, mergesTotalDocs): The number of merged documents.
- merges.total_size (or mts, mergesTotalSize): The total size of merges. For example: 0b.
- merges.total_time (or mtt, mergesTotalTime): The time spent merging documents. For example: 0s.
- name (or n): The node name.
- node.role (or r, role, nodeRole): The roles of the node. Returned values include c (cold node), d (data node), f (frozen node), h (hot node), i (ingest node), l (machine learning node), m (master-eligible node), r (remote cluster client node), s (content node), t (transform node), v (voting-only node), w (warm node), and - (coordinating node only). For example, dim indicates a master-eligible data and ingest node.
- pid (or p): The process identifier.
- port (or po): The bound transport port number.
- query_cache.memory_size (or qcm, queryCacheMemory): The used query cache memory. For example: 0b.
- query_cache.evictions (or qce, queryCacheEvictions): The number of query cache evictions.
- query_cache.hit_count (or qchc, queryCacheHitCount): The query cache hit count.
- query_cache.miss_count (or qcmc, queryCacheMissCount): The query cache miss count.
- ram.current (or rc, ramCurrent): The used total memory. For example: 513.4mb.
- ram.max (or rm, ramMax): The total memory. For example: 2.9gb.
- ram.percent (or rp, ramPercent): The used percentage of the total operating system memory. This reflects all processes running on the operating system instead of only Elasticsearch and is not guaranteed to correlate to its performance.
- refresh.total (or rto, refreshTotal): The number of refresh operations.
- refresh.time (or rti, refreshTime): The time spent in refresh operations. For example: 91ms.
- request_cache.memory_size (or rcm, requestCacheMemory): The used request cache memory. For example: 0b.
- request_cache.evictions (or rce, requestCacheEvictions): The number of request cache evictions.
- request_cache.hit_count (or rchc, requestCacheHitCount): The request cache hit count.
- request_cache.miss_count (or rcmc, requestCacheMissCount): The request cache miss count.
- script.compilations (or scrcc, scriptCompilations): The number of total script compilations.
- script.cache_evictions (or scrce, scriptCacheEvictions): The number of total compiled scripts evicted from cache.
- search.fetch_current (or sfc, searchFetchCurrent): The number of current fetch phase operations.
- search.fetch_time (or sfti, searchFetchTime): The time spent in fetch phase. For example: 37ms.
- search.fetch_total (or sfto, searchFetchTotal): The number of fetch operations.
- search.open_contexts (or so, searchOpenContexts): The number of open search contexts.
- search.query_current (or sqc, searchQueryCurrent): The number of current query phase operations.
- search.query_time (or sqti, searchQueryTime): The time spent in query phase. For example: 43ms.
- search.query_total (or sqto, searchQueryTotal): The number of query operations.
- search.scroll_current (or scc, searchScrollCurrent): The number of open scroll contexts.
- search.scroll_time (or scti, searchScrollTime): The amount of time scroll contexts were held open. For example: 2m.
- search.scroll_total (or scto, searchScrollTotal): The number of completed scroll contexts.
- segments.count (or sc, segmentsCount): The number of segments.
- segments.fixed_bitset_memory (or sfbm, fixedBitsetMemory): The memory used by fixed bit sets for nested object field types and type filters for types referred in join fields. For example: 1.0kb.
- segments.index_writer_memory (or siwm, segmentsIndexWriterMemory): The memory used by the index writer. For example: 18mb.
- segments.memory (or sm, segmentsMemory): The memory used by segments. For example: 1.4kb.
- segments.version_map_memory (or svmm, segmentsVersionMapMemory): The memory used by the version map. For example: 1.0kb.
- shard_stats.total_count (or sstc, shards, shardStatsTotalCount): The number of shards assigned.
- suggest.current (or suc, suggestCurrent): The number of current suggest operations.
- suggest.time (or suti, suggestTime): The time spent in suggest operations.
- suggest.total (or suto, suggestTotal): The number of suggest operations.
- uptime (or u): The amount of node uptime. For example: 17.3m.
- version (or v): The Elasticsearch version. For example: 9.0.0.
s string | array[string]

A comma-separated list of column names or aliases that determines the sort order. Sorting defaults to ascending and can be changed by setting :asc or :desc as a suffix to the column name.
master_timeout string

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

Values are -1 or 0.
time string

The 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
- pid string
  
  The process identifier.
- ip string
  
  The IP address.
- port string
  
  The bound transport port.
- http_address string
  
  The bound HTTP address.
- version string
- flavor string
  
  The Elasticsearch distribution flavor.
- type string
  
  The Elasticsearch distribution type.
- build string
  
  The Elasticsearch build hash.
- jdk string
  
  The Java version.
- disk.total number | string
  
  One of:
  number-1 number string-2 string
- disk.used number | string
  
  One of:
  number-1 number string-2 string
- disk.avail number | string
  
  One of:
  number-1 number string-2 string
- disk.used_percent string | number
  
  One of:
  string-1 string number-2 number
- heap.current string
  
  The used heap.
- heap.percent string | number
  
  One of:
  string-1 string number-2 number
- heap.max string
  
  The maximum configured heap.
- ram.current string
  
  The used machine memory.
- ram.percent string | number
  
  One of:
  string-1 string number-2 number
- ram.max string
  
  The total machine memory.
- file_desc.current string
  
  The used file descriptors.
- file_desc.percent string | number
  
  One of:
  string-1 string number-2 number
- file_desc.max string
  
  The maximum number of file descriptors.
- cpu string
  
  The recent system CPU usage as a percentage.
- load_1m string
  
  The load average for the most recent minute.
- load_5m string
  
  The load average for the last five minutes.
- load_15m string
  
  The load average for the last fifteen minutes.
- uptime string
  
  The node uptime.
- node.role string
  
  The roles of the node. Returned values include c(cold node), d(data node), f(frozen node), h(hot node), i(ingest node), l(machine learning node), m (master eligible node), r(remote cluster client node), s(content node), t(transform node), v(voting-only node), w(warm node),and -(coordinating node only).
- master string
  
  Indicates whether the node is the elected master node. Returned values include *(elected master) and -(not elected master).
- name string
- completion.size string
  
  The size of completion.
- fielddata.memory_size string
  
  The used fielddata cache.
- fielddata.evictions string
  
  The fielddata evictions.
- query_cache.memory_size string
  
  The used query cache.
- query_cache.evictions string
  
  The query cache evictions.
- query_cache.hit_count string
  
  The query cache hit counts.
- query_cache.miss_count string
  
  The query cache miss counts.
- request_cache.memory_size string
  
  The used request cache.
- request_cache.evictions string
  
  The request cache evictions.
- request_cache.hit_count string
  
  The request cache hit counts.
- request_cache.miss_count string
  
  The request cache miss counts.
- flush.total string
  
  The number of flushes.
- flush.total_time string
  
  The time spent in flush.
- get.current string
  
  The number of current get ops.
- get.time string
  
  The time spent in get.
- get.total string
  
  The number of get ops.
- get.exists_time string
  
  The time spent in successful gets.
- get.exists_total string
  
  The number of successful get operations.
- get.missing_time string
  
  The time spent in failed gets.
- get.missing_total string
  
  The number of failed gets.
- indexing.delete_current string
  
  The number of current deletions.
- indexing.delete_time string
  
  The time spent in deletions.
- indexing.delete_total string
  
  The number of delete operations.
- indexing.index_current string
  
  The number of current indexing operations.
- indexing.index_time string
  
  The time spent in indexing.
- indexing.index_total string
  
  The number of indexing operations.
- indexing.index_failed string
  
  The number of failed indexing operations.
- merges.current string
  
  The number of current merges.
- merges.current_docs string
  
  The number of current merging docs.
- merges.current_size string
  
  The size of current merges.
- merges.total string
  
  The number of completed merge operations.
- merges.total_docs string
  
  The docs merged.
- merges.total_size string
  
  The size merged.
- merges.total_time string
  
  The time spent in merges.
- refresh.total string
  
  The total refreshes.
- refresh.time string
  
  The time spent in refreshes.
- refresh.external_total string
  
  The total external refreshes.
- refresh.external_time string
  
  The time spent in external refreshes.
- refresh.listeners string
  
  The number of pending refresh listeners.
- script.compilations string
  
  The total script compilations.
- script.cache_evictions string
  
  The total compiled scripts evicted from the cache.
- script.compilation_limit_triggered string
  
  The script cache compilation limit triggered.
- search.fetch_current string
  
  The current fetch phase operations.
- search.fetch_time string
  
  The time spent in fetch phase.
- search.fetch_total string
  
  The total fetch operations.
- search.open_contexts string
  
  The open search contexts.
- search.query_current string
  
  The current query phase operations.
- search.query_time string
  
  The time spent in query phase.
- search.query_total string
  
  The total query phase operations.
- search.scroll_current string
  
  The open scroll contexts.
- search.scroll_time string
  
  The time scroll contexts held open.
- search.scroll_total string
  
  The completed scroll contexts.
- segments.count string
  
  The number of segments.
- segments.memory string
  
  The memory used by segments.
- segments.index_writer_memory string
  
  The memory used by the index writer.
- segments.version_map_memory string
  
  The memory used by the version map.
- segments.fixed_bitset_memory string
  
  The memory used by fixed bit sets for nested object field types and export type filters for types referred in _parent fields.
- suggest.current string
  
  The number of current suggest operations.
- suggest.time string
  
  The time spend in suggest.
- suggest.total string
  
  The number of suggest operations.
- bulk.total_operations string
  
  The number of bulk shard operations.
- bulk.total_time string
  
  The time spend in shard bulk.
- bulk.total_size_in_bytes string
  
  The total size in bytes of shard bulk.
- bulk.avg_time string
  
  The average time spend in shard bulk.
- bulk.avg_size_in_bytes string
  
  The average size in bytes of shard bulk.

GET /_cat/nodes

GET /_cat/nodes?v=true&h=id,ip,port,v,m&format=json

resp = client.cat.nodes(
    v=True,
    h="id,ip,port,v,m",
    format="json",
)

const response = await client.cat.nodes({
  v: "true",
  h: "id,ip,port,v,m",
  format: "json",
});

response = client.cat.nodes(
  v: "true",
  h: "id,ip,port,v,m",
  format: "json"
)

$resp = $client->cat()->nodes([
    "v" => "true",
    "h" => "id,ip,port,v,m",
    "format" => "json",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_cat/nodes?v=true&h=id,ip,port,v,m&format=json"

client.cat().nodes();

Response examples (200)

A successful response from `GET /_cat/nodes?v=true&format=json`. The `ip`, `heap.percent`, `ram.percent`, `cpu`, and `load_*` columns provide the IP addresses and performance information of each node. The `node.role`, `master`, and `name` columns provide information useful for monitoring an entire cluster, particularly large ones.

[
  {
    "ip": "127.0.0.1",
    "heap.percent": "65",
    "ram.percent": "99",
    "cpu": "42",
    "load_1m": "3.07",
    "load_5m": null,
    "load_15m": null,
    "node.role": "cdfhilmrstw",
    "master": "*",
    "name": "mJw06l1"
  }
]

A successful response from `GET /_cat/nodes?v=true&h=id,ip,port,v,m&format=json`. It returns the `id`, `ip`, `port`, `v` (version), and `m` (master) columns.

[
  {
    "id": "veJR",
    "ip": "127.0.0.1",
    "port": "59938",
    "v": "9.0.0",
    "m": "*"
  }
]

Explain the shard allocations Generally available; Added in 5.0.0

POST /_cluster/allocation/explain

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_cluster/allocation/explain

POST /_cluster/allocation/explain

Get explanations for shard allocations in the cluster. For unassigned shards, it provides an explanation for why the shard is unassigned. For assigned shards, it provides an explanation for why the shard is remaining on its current node and has not moved or rebalanced to another node. This API can be very useful when attempting to diagnose why a shard is unassigned or why a shard continues to remain on its current node when you might expect otherwise.

Query parameters

include_disk_info boolean

If true, returns information about disk usage and shard sizes.
include_yes_decisions boolean

If true, returns YES decisions in explanation.
master_timeout string

Period to wait for a connection to the master node.

Values are -1 or 0.

application/json

Body

current_node string

Specifies the node ID or the name of the node to only explain a shard that is currently located on the specified node.
index string
primary boolean

If true, returns explanation for the primary shard for the given shard ID.
shard number

Specifies the ID of the shard that you would like an explanation for.

Responses

200 application/json
Hide response attributes Show response attributes object
- allocate_explanation string
- allocation_delay 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.
- allocation_delay_in_millis number
  
  Time unit for milliseconds
- can_allocate string
  
  Values are yes, no, worse_balance, throttled, awaiting_info, allocation_delayed, no_valid_shard_copy, or no_attempt.
- can_move_to_other_node string
  
  Values are yes, no, worse_balance, throttled, awaiting_info, allocation_delayed, no_valid_shard_copy, or no_attempt.
- can_rebalance_cluster string
  
  Values are yes, no, worse_balance, throttled, awaiting_info, allocation_delayed, no_valid_shard_copy, or no_attempt.
- can_rebalance_cluster_decisions array[object]
  
  Hide can_rebalance_cluster_decisions attributes Show can_rebalance_cluster_decisions attributes object
  
  decider string Required
  
  decision string Required
  
  Values are NO, YES, THROTTLE, or ALWAYS.
  
  explanation string Required
- can_rebalance_to_other_node string
  
  Values are yes, no, worse_balance, throttled, awaiting_info, allocation_delayed, no_valid_shard_copy, or no_attempt.
- can_remain_decisions array[object]
  
  Hide can_remain_decisions attributes Show can_remain_decisions attributes object
  
  decider string Required
  
  decision string Required
  
  Values are NO, YES, THROTTLE, or ALWAYS.
  
  explanation string Required
- can_remain_on_current_node string
  
  Values are yes, no, worse_balance, throttled, awaiting_info, allocation_delayed, no_valid_shard_copy, or no_attempt.
- cluster_info object
  
  Hide cluster_info attributes Show cluster_info attributes object
  
  nodes object Required
  
  Hide nodes attribute Show nodes attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  node_name string Required
  
  least_available object Required
  
  Hide least_available attributes Show least_available attributes object
  
  path string Required
  
  total_bytes number Required
  
  used_bytes number Required
  
  free_bytes number Required
  
  free_disk_percent number Required
  
  used_disk_percent number Required
  
  most_available object Required
  
  Hide most_available attributes Show most_available attributes object
  
  path string Required
  
  total_bytes number Required
  
  used_bytes number Required
  
  free_bytes number Required
  
  free_disk_percent number Required
  
  used_disk_percent number Required
  
  shard_sizes object Required
  
  Hide shard_sizes attribute Show shard_sizes attribute object
  
  * number Additional properties
  
  shard_data_set_sizes object
  
  Hide shard_data_set_sizes attribute Show shard_data_set_sizes attribute object
  
  * string Additional properties
  
  shard_paths object Required
  
  Hide shard_paths attribute Show shard_paths attribute object
  
  * string Additional properties
  
  reserved_sizes array[object] Required
  
  Hide reserved_sizes attributes Show reserved_sizes attributes object
  
  node_id string Required
  
  path string Required
  
  total number Required
  
  shards array[string] Required
- configured_delay 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.
- configured_delay_in_millis number
  
  Time unit for milliseconds
- current_node object
  
  Hide current_node attributes Show current_node attributes object
  
  id string Required
  
  name string Required
  
  roles array[string] Required
  
  Values are master, data, data_cold, data_content, data_frozen, data_hot, data_warm, client, ingest, ml, voting_only, transform, remote_cluster_client, or coordinating_only.
  
  attributes object Required
  
  Hide attributes attribute Show attributes attribute object
  
  * string Additional properties
  
  transport_address string Required
  
  weight_ranking number Required
- current_state string Required
- index string Required
- move_explanation string
- node_allocation_decisions array[object]
  
  Hide node_allocation_decisions attributes Show node_allocation_decisions attributes object
  
  deciders array[object] Required
  
  Hide deciders attributes Show deciders attributes object
  
  decider string Required
  
  decision string Required
  
  Values are NO, YES, THROTTLE, or ALWAYS.
  
  explanation string Required
  
  node_attributes object Required
  
  Hide node_attributes attribute Show node_attributes attribute object
  
  * string Additional properties
  
  node_decision string Required
  
  Values are yes, no, worse_balance, throttled, awaiting_info, allocation_delayed, no_valid_shard_copy, or no_attempt.
  
  node_id string Required
  
  node_name string Required
  
  roles array[string] Required
  
  Values are master, data, data_cold, data_content, data_frozen, data_hot, data_warm, client, ingest, ml, voting_only, transform, remote_cluster_client, or coordinating_only.
  
  store object
  
  Hide store attributes Show store attributes object
  
  allocation_id string Required
  
  found boolean Required
  
  in_sync boolean Required
  
  matching_size_in_bytes number Required
  
  matching_sync_id boolean Required
  
  store_exception string Required
  
  transport_address string Required
  
  weight_ranking number Required
- primary boolean Required
- rebalance_explanation string
- remaining_delay 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.
- remaining_delay_in_millis number
  
  Time unit for milliseconds
- shard number Required
- unassigned_info object
  
  Hide unassigned_info attributes Show unassigned_info attributes object
  
  at string | number Required
  
  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:
  string-1 string UnitMillis number
  
  last_allocation_status string
  
  reason string Required
  
  Values are INDEX_CREATED, CLUSTER_RECOVERED, INDEX_REOPENED, DANGLING_INDEX_IMPORTED, NEW_INDEX_RESTORED, EXISTING_INDEX_RESTORED, REPLICA_ADDED, ALLOCATION_FAILED, NODE_LEFT, REROUTE_CANCELLED, REINITIALIZED, REALLOCATED_REPLICA, PRIMARY_FAILED, FORCED_EMPTY_PRIMARY, or MANUAL_ALLOCATION.
  
  details string
  
  failed_allocation_attempts number
  
  delayed boolean
  
  allocation_status string
- note string Generally available; Added in 7.14.0

POST /_cluster/allocation/explain

GET _cluster/allocation/explain
{
  "index": "my-index-000001",
  "shard": 0,
  "primary": false,
  "current_node": "my-node"
}

resp = client.cluster.allocation_explain(
    index="my-index-000001",
    shard=0,
    primary=False,
    current_node="my-node",
)

const response = await client.cluster.allocationExplain({
  index: "my-index-000001",
  shard: 0,
  primary: false,
  current_node: "my-node",
});

response = client.cluster.allocation_explain(
  body: {
    "index": "my-index-000001",
    "shard": 0,
    "primary": false,
    "current_node": "my-node"
  }
)

$resp = $client->cluster()->allocationExplain([
    "body" => [
        "index" => "my-index-000001",
        "shard" => 0,
        "primary" => false,
        "current_node" => "my-node",
    ],
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"index":"my-index-000001","shard":0,"primary":false,"current_node":"my-node"}' "$ELASTICSEARCH_URL/_cluster/allocation/explain"

client.cluster().allocationExplain(a -> a
    .currentNode("my-node")
    .index("my-index-000001")
    .primary(false)
    .shard(0)
);

Request example

Run `GET _cluster/allocation/explain` to get an explanation for a shard's current allocation.

{
  "index": "my-index-000001",
  "shard": 0,
  "primary": false,
  "current_node": "my-node"
}

Response examples (200)

An example of an allocation explanation for an unassigned primary shard. In this example, a newly created index has an index setting that requires that it only be allocated to a node named `nonexistent_node`, which does not exist, so the index is unable to allocate.

{
  "index" : "my-index-000001",
  "shard" : 0,
  "primary" : true,
  "current_state" : "unassigned",
  "unassigned_info" : {
    "reason" : "INDEX_CREATED",
    "at" : "2017-01-04T18:08:16.600Z",
    "last_allocation_status" : "no"
  },
  "can_allocate" : "no",
  "allocate_explanation" : "Elasticsearch isn't allowed to allocate this shard to any of the nodes in the cluster. Choose a node to which you expect this shard to be allocated, find this node in the node-by-node explanation, and address the reasons which prevent Elasticsearch from allocating this shard there.",
  "node_allocation_decisions" : [
    {
      "node_id" : "8qt2rY-pT6KNZB3-hGfLnw",
      "node_name" : "node-0",
      "transport_address" : "127.0.0.1:9401",
      "roles" : ["data", "data_cold", "data_content", "data_frozen", "data_hot", "data_warm", "ingest", "master", "ml", "remote_cluster_client", "transform"],
      "node_attributes" : {},
      "node_decision" : "no",
      "weight_ranking" : 1,
      "deciders" : [
        {
          "decider" : "filter",
          "decision" : "NO",
          "explanation" : "node does not match index setting [index.routing.allocation.include] filters [_name:\"nonexistent_node\"]"
        }
      ]
    }
  ]
}

An example of an allocation explanation for an unassigned primary shard that has reached the maximum number of allocation retry attempts. After the maximum number of retries is reached, Elasticsearch stops attempting to allocate the shard in order to prevent infinite retries which may impact cluster performance.

{
  "index" : "my-index-000001",
  "shard" : 0,
  "primary" : true,
  "current_state" : "unassigned",
  "unassigned_info" : {
    "at" : "2017-01-04T18:03:28.464Z",
    "failed shard on node [mEKjwwzLT1yJVb8UxT6anw]: failed recovery, failure RecoveryFailedException",
    "reason": "ALLOCATION_FAILED",
    "failed_allocation_attempts": 5,
    "last_allocation_status": "no",
  },
  "can_allocate": "no",
  "allocate_explanation": "cannot allocate because allocation is not permitted to any of the nodes",
  "node_allocation_decisions" : [
    {
      "node_id" : "3sULLVJrRneSg0EfBB-2Ew",
      "node_name" : "node_t0",
      "transport_address" : "127.0.0.1:9400",
      "roles" : ["data_content", "data_hot"],
      "node_decision" : "no",
      "store" : {
        "matching_size" : "4.2kb",
        "matching_size_in_bytes" : 4325
      },
      "deciders" : [
        {
          "decider": "max_retry",
          "decision" : "NO",
          "explanation": "shard has exceeded the maximum number of retries [5] on failed allocation attempts - manually call [POST /_cluster/reroute?retry_failed] to retry, [unassigned_info[[reason=ALLOCATION_FAILED], at[2024-07-30T21:04:12.166Z], failed_attempts[5], failed_nodes[[mEKjwwzLT1yJVb8UxT6anw]], delayed=false, details[failed shard on node [mEKjwwzLT1yJVb8UxT6anw]: failed recovery, failure RecoveryFailedException], allocation_status[deciders_no]]]"
        }
      ]
    }
  ]
}

Clear the archived repositories metering Technical preview; Added in 7.16.0

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.

Required authorization

Cluster privileges: monitor,manage

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
  
  Contains statistics about the number of nodes selected by the request.
  
  Hide _nodes attributes Show _nodes attributes object
  
  failures array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide failures attributes Show failures attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  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"

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

Update the connector API key ID Beta; Added in 8.12.0

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

PUT _connector/my-connector/_api_key_id
{
    "api_key_id": "my-api-key-id",
    "api_key_secret_id": "my-connector-secret-id"
}

resp = client.connector.update_api_key_id(
    connector_id="my-connector",
    api_key_id="my-api-key-id",
    api_key_secret_id="my-connector-secret-id",
)

const response = await client.connector.updateApiKeyId({
  connector_id: "my-connector",
  api_key_id: "my-api-key-id",
  api_key_secret_id: "my-connector-secret-id",
});

response = client.connector.update_api_key_id(
  connector_id: "my-connector",
  body: {
    "api_key_id": "my-api-key-id",
    "api_key_secret_id": "my-connector-secret-id"
  }
)

$resp = $client->connector()->updateApiKeyId([
    "connector_id" => "my-connector",
    "body" => [
        "api_key_id" => "my-api-key-id",
        "api_key_secret_id" => "my-connector-secret-id",
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"api_key_id":"my-api-key-id","api_key_secret_id":"my-connector-secret-id"}' "$ELASTICSEARCH_URL/_connector/my-connector/_api_key_id"

client.connector().updateApiKeyId(u -> u
    .apiKeyId("my-api-key-id")
    .apiKeySecretId("my-connector-secret-id")
    .connectorId("my-connector")
);

Request example

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

Response examples (200)

{
  "result": "updated"
}

Delete documents Generally available; Added in 5.0.0

POST /{index}/_delete_by_query

Api key auth Basic auth Bearer auth

Deletes documents that match the specified query.

If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or alias:

read
delete or write

You can specify the query criteria in the request URI or the request body using the same syntax as the search API. When you submit a delete by query request, Elasticsearch gets a snapshot of the data stream or index when it begins processing the request and deletes matching documents using internal versioning. If a document changes between the time that the snapshot is taken and the delete operation is processed, it results in a version conflict and the delete operation fails.

NOTE: Documents with a version equal to 0 cannot be deleted using delete by query because internal versioning does not support 0 as a valid version number.

While processing a delete by query request, Elasticsearch performs multiple search requests sequentially to find all of the matching documents to delete. A bulk delete request is performed for each batch of matching documents. If a search or bulk request is rejected, the requests are retried up to 10 times, with exponential back off. If the maximum retry limit is reached, processing halts and all failed requests are returned in the response. Any delete requests that completed successfully still stick, they are not rolled back.

You can opt to count version conflicts instead of halting and returning by setting conflicts to proceed. Note that if you opt to count version conflicts the operation could attempt to delete more documents from the source than max_docs until it has successfully deleted max_docs documents, or it has gone through every document in the source query.

Throttling delete requests

To control the rate at which delete by query issues batches of delete operations, you can set requests_per_second to any positive decimal number. This pads each batch with a wait time to throttle the rate. Set requests_per_second to -1 to disable throttling.

Throttling uses a wait time between batches so that the internal scroll requests can be given a timeout that takes the request padding into account. The padding time is the difference between the batch size divided by the requests_per_second and the time spent writing. By default the batch size is 1000, so if requests_per_second is set to 500:

target_time = 1000 / 500 per second = 2 seconds
wait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds

Since the batch is issued as a single _bulk request, large batch sizes cause Elasticsearch to create many requests and wait before starting the next set. This is "bursty" instead of "smooth".

Slicing

Delete by query supports sliced scroll to parallelize the delete process. This can improve efficiency and provide a convenient way to break the request down into smaller parts.

Setting slices to auto lets Elasticsearch choose the number of slices to use. This setting will use one slice per shard, up to a certain limit. If there are multiple source data streams or indices, it will choose the number of slices based on the index or backing index with the smallest number of shards. Adding slices to the delete by query operation creates sub-requests which means it has some quirks:

You can see these requests in the tasks APIs. These sub-requests are "child" tasks of the task for the request with slices.
Fetching the status of the task for the request with slices only contains the status of completed slices.
These sub-requests are individually addressable for things like cancellation and rethrottling.
Rethrottling the request with slices will rethrottle the unfinished sub-request proportionally.
Canceling the request with slices will cancel each sub-request.
Due to the nature of slices each sub-request won't get a perfectly even portion of the documents. All documents will be addressed, but some slices may be larger than others. Expect larger slices to have a more even distribution.
Parameters like requests_per_second and max_docs on a request with slices are distributed proportionally to each sub-request. Combine that with the earlier point about distribution being uneven and you should conclude that using max_docs with slices might not result in exactly max_docs documents being deleted.
Each sub-request gets a slightly different snapshot of the source data stream or index though these are all taken at approximately the same time.

If you're slicing manually or otherwise tuning automatic slicing, keep in mind that:

Query performance is most efficient when the number of slices is equal to the number of shards in the index or backing index. If that number is large (for example, 500), choose a lower number as too many slices hurts performance. Setting slices higher than the number of shards generally does not improve efficiency and adds overhead.
Delete performance scales linearly across available resources with the number of slices.

Whether query or delete performance dominates the runtime depends on the documents being reindexed and cluster resources.

Cancel a delete by query operation

Any delete by query can be canceled using the task cancel API. For example:

POST _tasks/r1A2WoRbTwKZ516z6NEs5A:36619/_cancel

The task ID can be found by using the get tasks API.

Cancellation should happen quickly but might take a few seconds. The get task status API will continue to list the delete by query task until this task checks that it has been cancelled and terminates itself.

Required authorization

Index privileges: read,delete

Path parameters

index string | array[string] Required

A comma-separated list of data streams, indices, and aliases to search. It supports wildcards (*). To search all data streams or 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. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
analyzer string

Analyzer to use for the query string. This parameter can be used only when the q query string parameter is specified.
analyze_wildcard boolean

If true, wildcard and prefix queries are analyzed. This parameter can be used only when the q query string parameter is specified.
conflicts string
What to do if delete by query hits version conflicts: abort or proceed.

Supported values include:
- abort: Stop reindexing if there are conflicts.
- proceed: Continue reindexing even if there are conflicts.
Values are abort or proceed.
default_operator string

The default operator for query string query: AND or OR. This parameter can be used only when the q query string parameter is specified.

Values are and, AND, or, or OR.
df string

The field to use as default where no field prefix is given in the query string. This parameter can be used only when the q query string parameter is specified.
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.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
Values are all, open, closed, hidden, or none.
from number

Skips the specified number of documents.
ignore_unavailable boolean

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

If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. This parameter can be used only when the q query string parameter is specified.
max_docs number

The maximum number of documents to process. Defaults to all documents. When set to a value less then or equal to scroll_size, a scroll will not be used to retrieve the results for the operation.
preference string

The node or shard the operation should be performed on. It is random by default.
refresh boolean

If true, Elasticsearch refreshes all shards involved in the delete by query after the request completes. This is different than the delete API's refresh parameter, which causes just the shard that received the delete request to be refreshed. Unlike the delete API, it does not support wait_for.
request_cache boolean

If true, the request cache is used for this request. Defaults to the index-level setting.
requests_per_second number

The throttle for this request in sub-requests per second.
routing string

A custom value used to route operations to a specific shard.
q string

A query in the Lucene query string syntax.
scroll string

The period to retain the search context for scrolling.

Values are -1 or 0.
scroll_size number

The size of the scroll request that powers the operation.
search_timeout string

The explicit timeout for each search request. It defaults to no timeout.

Values are -1 or 0.
search_type string
The type of the search operation. Available options include query_then_fetch and dfs_query_then_fetch.

Supported values include:
- query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.
- dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.
Values are query_then_fetch or dfs_query_then_fetch.
slices number | string

The number of slices this task should be divided into.

Value is auto.
sort array[string]

A comma-separated list of <field>:<direction> pairs.
stats array[string]

The specific tag of the request for logging and statistical purposes.
terminate_after number

The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.

Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers.
timeout string

The period each deletion request waits for active shards.

Values are -1 or 0.
version boolean

If true, returns the document version as part of a hit.
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). The timeout value controls how long each write request waits for unavailable shards to become available.

Values are all or index-setting.
wait_for_completion boolean

If true, the request blocks until the operation is complete. If false, Elasticsearch performs some preflight checks, launches the request, and returns a task you can use to cancel or get the status of the task. Elasticsearch creates a record of this task as a document at .tasks/task/${taskId}. When you are done with a task, you should delete the task document so Elasticsearch can reclaim the space.

application/json

Body Required

max_docs number

The maximum number of documents to delete.
query object

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

External documentation
slice object
Hide slice attributes Show slice attributes object
- field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- id string Required
- max number Required

Responses

200 application/json
Hide response attributes Show response attributes object
- batches number
  
  The number of scroll responses pulled back by the delete by query.
- deleted number
  
  The number of documents that were successfully deleted.
- failures array[object]
  
  An array of failures if there were any unrecoverable errors during the process. If this array is not empty, the request ended abnormally because of those failures. Delete by query is implemented using batches and any failures cause the entire process to end but all failures in the current batch are collected into the array. You can use the conflicts option to prevent reindex from ending on version conflicts.
  
  Hide failures attributes Show failures attributes object
  
  cause object Required
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Hide cause attributes Show cause attributes object
  
  type string Required
  
  The type of error
  
  reason string | null
  
  A human-readable explanation of the error, in English.
  
  One of:
  string-1 string string-2 string | null
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  root_cause array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  suppressed array[object]
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.
  
  id string Required
  
  index string Required
  
  status number Required
- noops number
  
  This field is always equal to zero for delete by query. It exists only so that delete by query, update by query, and reindex APIs return responses with the same structure.
- requests_per_second number
  
  The number of requests per second effectively run during the delete by query.
- retries object
  
  Hide retries attributes Show retries attributes object
  
  bulk number Required
  
  The number of bulk actions retried.
  
  search number Required
  
  The number of search actions retried.
- slice_id number
- task string | number
  
  One of:
  string-1 string number-2 number
- throttled 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.
- throttled_millis number
  
  Time unit for milliseconds
- throttled_until 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.
- throttled_until_millis number
  
  Time unit for milliseconds
- timed_out boolean
  
  If true, some requests run during the delete by query operation timed out.
- took number
  
  Time unit for milliseconds
- total number
  
  The number of documents that were successfully processed.
- version_conflicts number
  
  The number of version conflicts that the delete by query hit.

POST /{index}/_delete_by_query

POST /my-index-000001,my-index-000002/_delete_by_query
{
  "query": {
    "match_all": {}
  }
}

resp = client.delete_by_query(
    index="my-index-000001,my-index-000002",
    query={
        "match_all": {}
    },
)

const response = await client.deleteByQuery({
  index: "my-index-000001,my-index-000002",
  query: {
    match_all: {},
  },
});

response = client.delete_by_query(
  index: "my-index-000001,my-index-000002",
  body: {
    "query": {
      "match_all": {}
    }
  }
)

$resp = $client->deleteByQuery([
    "index" => "my-index-000001,my-index-000002",
    "body" => [
        "query" => [
            "match_all" => new ArrayObject([]),
        ],
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":{"match_all":{}}}' "$ELASTICSEARCH_URL/my-index-000001,my-index-000002/_delete_by_query"

client.deleteByQuery(d -> d
    .index(List.of("my-index-000001","my-index-000002"))
    .query(q -> q
        .matchAll(m -> m)
    )
);

Request examples

Run `POST /my-index-000001,my-index-000002/_delete_by_query` to delete all documents from multiple data streams or indices.

{
  "query": {
    "match_all": {}
  }
}

Run `POST my-index-000001/_delete_by_query` to delete a document by using a unique attribute.

{
  "query": {
    "term": {
      "user.id": "kimchy"
    }
  },
  "max_docs": 1
}

Run `POST my-index-000001/_delete_by_query` to slice a delete by query manually. Provide a slice ID and total number of slices.

{
  "slice": {
    "id": 0,
    "max": 2
  },
  "query": {
    "range": {
      "http.response.bytes": {
        "lt": 2000000
      }
    }
  }
}

Run `POST my-index-000001/_delete_by_query?refresh&slices=5` to let delete by query automatically parallelize using sliced scroll to slice on `_id`. The `slices` query parameter value specifies the number of slices to use.

{
  "query": {
    "range": {
      "http.response.bytes": {
        "lt": 2000000
      }
    }
  }
}

Response examples (200)

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

{
  "took" : 147,
  "timed_out": false,
  "total": 119,
  "deleted": 119,
  "batches": 1,
  "version_conflicts": 0,
  "noops": 0,
  "retries": {
    "bulk": 0,
    "search": 0
  },
  "throttled_millis": 0,
  "requests_per_second": -1.0,
  "throttled_until_millis": 0,
  "failures" : [ ]
}

Delete an enrich policy Generally available; Added in 7.5.0

DELETE /_enrich/policy/{name}

Api key auth Basic auth Bearer auth

Deletes an existing enrich policy and its enrich index.

Path parameters

name string Required

Enrich policy to delete.

Query parameters

master_timeout string

Period to wait for a connection to the master node.

Values are -1 or 0.

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 /_enrich/policy/{name}

DELETE /_enrich/policy/my-policy

resp = client.enrich.delete_policy(
    name="my-policy",
)

const response = await client.enrich.deletePolicy({
  name: "my-policy",
});

response = client.enrich.delete_policy(
  name: "my-policy"
)

$resp = $client->enrich()->deletePolicy([
    "name" => "my-policy",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_enrich/policy/my-policy"

client.enrich().deletePolicy(d -> d
    .name("my-policy")
);

Run an async ES|QL query Generally available; Added in 8.13.0

POST /_query/async

Api key auth Basic auth Bearer auth

Asynchronously run an ES|QL (Elasticsearch query language) query, monitor its progress, and retrieve results when they become available.

The API accepts the same parameters and request body as the synchronous query API, along with additional async related properties.

Required authorization

Index privileges: read

External documentation

Query parameters

delimiter string

The character to use between values within a CSV row. It is valid only for the CSV format.
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.
format string

A short version of the Accept header, for example json or yaml.

Values are csv, json, tsv, txt, yaml, cbor, smile, or arrow.

application/json

Body Required

columnar boolean

By default, ES|QL returns results as rows. For example, FROM returns each individual document as one row. For the JSON, YAML, CBOR and smile formats, ES|QL can return the results in a columnar fashion where one row represents all the values of a certain column in the results.
filter object

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

External documentation
locale string
params array[number | string | boolean | null | object]

To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) in the query string for each of the parameters.

A field value.

A field value.

One of:
number-1 number number-2 number string-3 string boolean-4 boolean string-5 string | null object-6 object
profile boolean

If provided and true the response will include an extra profile object with information on how the query was executed. This information is for human debugging and its format can change at any time but it can give some insight into the performance of each part of the query.
query string Required

The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.
tables object

Tables to use with the LOOKUP operation. The top level key is the table name and the next level key is the column name.
Hide tables attribute Show tables attribute object
- * object Additional properties
  Hide * attribute Show * attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  integer array[number | array]
  
  One of:
  number-1 number array-2 array[number]
  
  keyword array[string | array]
  
  One of:
  string-1 string array-2 array[string]
  
  long array[number | array]
  
  One of:
  number-1 number array-2 array[number]
  
  double array[number | array]
  
  One of:
  number-1 number array-2 array[number]
include_ccs_metadata boolean

When set to true and performing a cross-cluster query, the response will include an extra _clusters object with information about the clusters that participated in the search along with info such as shards count.

Default value is false.
wait_for_completion_timeout 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.
keep_alive 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.
keep_on_completion boolean

Indicates whether the query and its results are stored in the cluster. If false, the query and its results are stored in the cluster only if the request does not complete during the period set by the wait_for_completion_timeout parameter.

Default value is false.

Responses

200 application/json

POST /_query/async

POST /_query/async
{
  "query": """
    FROM library,remote-*:library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  """,
  "wait_for_completion_timeout": "2s",
  "include_ccs_metadata": true
}

resp = client.esql.async_query(
    query="\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
    wait_for_completion_timeout="2s",
    include_ccs_metadata=True,
)

const response = await client.esql.asyncQuery({
  query:
    "\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
  wait_for_completion_timeout: "2s",
  include_ccs_metadata: true,
});

response = client.esql.async_query(
  body: {
    "query": "\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
    "wait_for_completion_timeout": "2s",
    "include_ccs_metadata": true
  }
)

$resp = $client->esql()->asyncQuery([
    "body" => [
        "query" => "\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
        "wait_for_completion_timeout" => "2s",
        "include_ccs_metadata" => true,
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":"\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ","wait_for_completion_timeout":"2s","include_ccs_metadata":true}' "$ELASTICSEARCH_URL/_query/async"

Request example

{
  "query": """
    FROM library,remote-*:library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  """,
  "wait_for_completion_timeout": "2s",
  "include_ccs_metadata": true
}

Check component templates Generally available; Added in 7.8.0

HEAD /_component_template/{name}

Api key auth Basic auth Bearer auth

Returns information about whether a particular component template exists.

Path parameters

name string | array[string] Required

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

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.

Values are -1 or 0.
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.

Responses

200 application/json

HEAD /_component_template/{name}

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

Move to a lifecycle step Generally available; Added in 6.6.0

POST /_ilm/move/{index}

Api key auth Basic auth Bearer auth

Manually move an index into a specific step in the lifecycle policy and run that step.

WARNING: This operation can result in the loss of data. Manually moving an index into a specific step runs that step even if it has already been performed. This is a potentially destructive action and this should be considered an expert level API.

You must specify both the current step and the step to be executed in the body of the request. The request will fail if the current step does not match the step currently running for the index This is to prevent the index from being moved from an unexpected step into the next step.

When specifying the target (next_step) to which the index will be moved, either the name or both the action and name fields are optional. If only the phase is specified, the index will move to the first step of the first action in the target phase. If the phase and action are specified, the index will move to the first step of the specified action in the specified phase. Only actions specified in the ILM policy are considered valid. An index cannot move to a step that is not part of its policy.

Required authorization

Index privileges: manage_ilm

Path parameters

index string Required

The name of the index whose lifecycle step is to change

application/json

Body

current_step object Required
Hide current_step attributes Show current_step attributes object
- action string
  
  The optional action to which the index will be moved.
- name string
  
  The optional step name to which the index will be moved.
- phase string Required
next_step object Required
Hide next_step attributes Show next_step attributes object
- action string
  
  The optional action to which the index will be moved.
- name string
  
  The optional step name to which the index will be moved.
- phase string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- acknowledged boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

POST /_ilm/move/{index}

POST _ilm/move/my-index-000001
{
  "current_step": {
    "phase": "new",
    "action": "complete",
    "name": "complete"
  },
  "next_step": {
    "phase": "warm",
    "action": "forcemerge",
    "name": "forcemerge"
  }
}

resp = client.ilm.move_to_step(
    index="my-index-000001",
    current_step={
        "phase": "new",
        "action": "complete",
        "name": "complete"
    },
    next_step={
        "phase": "warm",
        "action": "forcemerge",
        "name": "forcemerge"
    },
)

const response = await client.ilm.moveToStep({
  index: "my-index-000001",
  current_step: {
    phase: "new",
    action: "complete",
    name: "complete",
  },
  next_step: {
    phase: "warm",
    action: "forcemerge",
    name: "forcemerge",
  },
});

response = client.ilm.move_to_step(
  index: "my-index-000001",
  body: {
    "current_step": {
      "phase": "new",
      "action": "complete",
      "name": "complete"
    },
    "next_step": {
      "phase": "warm",
      "action": "forcemerge",
      "name": "forcemerge"
    }
  }
)

$resp = $client->ilm()->moveToStep([
    "index" => "my-index-000001",
    "body" => [
        "current_step" => [
            "phase" => "new",
            "action" => "complete",
            "name" => "complete",
        ],
        "next_step" => [
            "phase" => "warm",
            "action" => "forcemerge",
            "name" => "forcemerge",
        ],
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"current_step":{"phase":"new","action":"complete","name":"complete"},"next_step":{"phase":"warm","action":"forcemerge","name":"forcemerge"}}' "$ELASTICSEARCH_URL/_ilm/move/my-index-000001"

client.ilm().moveToStep(m -> m
    .currentStep(c -> c
        .action("complete")
        .name("complete")
        .phase("new")
    )
    .index("my-index-000001")
    .nextStep(n -> n
        .action("forcemerge")
        .name("forcemerge")
        .phase("warm")
    )
);

Request examples

Run `POST _ilm/move/my-index-000001` to move `my-index-000001` from the initial step to the `forcemerge` step.

{
  "current_step": {
    "phase": "new",
    "action": "complete",
    "name": "complete"
  },
  "next_step": {
    "phase": "warm",
    "action": "forcemerge",
    "name": "forcemerge"
  }
}

Run `POST _ilm/move/my-index-000001` to move `my-index-000001` from the end of hot phase into the start of warm.

{
  "current_step": {
    "phase": "hot",
    "action": "complete",
    "name": "complete"
  },
  "next_step": {
    "phase": "warm"
  }
}

Response examples (200)

A successful response when running a specific step in a lifecycle policy.

{
  "acknowledged": true
}

Create an Azure AI studio inference endpoint Generally available; Added in 8.14.0

PUT /_inference/{task_type}/{azureaistudio_inference_id}

Api key auth Basic auth Bearer auth

Create an inference endpoint to perform an inference task with the azureaistudio service.

Required authorization

Cluster privileges: manage_inference

Path parameters

task_type string

The type of the inference task that the model will perform.

Values are completion or text_embedding.
azureaistudio_inference_id string Required

The unique identifier of the inference endpoint.

Query parameters

timeout string

Specifies the amount of time to wait for the inference endpoint to be created.

Values are -1 or 0.

application/json

Body

chunking_settings object

Chunking configuration object
Hide chunking_settings attributes Show chunking_settings attributes object
- max_chunk_size number
  
  The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).
  
  Default value is 250.
- overlap number
  
  The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.
  
  Default value is 100.
- sentence_overlap number
  
  The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.
  
  Default value is 1.
- strategy string
  
  The chunking strategy: sentence or word.
  
  Default value is sentence.
service string Required

Value is azureaistudio.
service_settings object Required
Hide service_settings attributes Show service_settings attributes object
- api_key string Required
  
  A valid API key of your Azure AI Studio model deployment. This key can be found on the overview page for your deployment in the management section of your Azure AI Studio account.
  
  IMPORTANT: You need to provide the API key only once, during the inference model creation. The get inference endpoint API does not retrieve your API key. After creating the inference model, you cannot change the associated API key. If you want to use a different API key, delete the inference model and recreate it with the same name and the updated API key.
  
  External documentation
- endpoint_type string Required
  
  The type of endpoint that is available for deployment through Azure AI Studio: token or realtime. The token endpoint type is for "pay as you go" endpoints that are billed per token. The realtime endpoint type is for "real-time" endpoints that are billed per hour of usage.
  
  External documentation
- target string Required
  
  The target URL of your Azure AI Studio model deployment. This can be found on the overview page for your deployment in the management section of your Azure AI Studio account.
- provider string Required
  The model provider for your deployment. Note that some providers may support only certain task types. Supported providers include:
  
  cohere - available for text_embedding and completion task types
  
  databricks - available for completion task type only
  
  meta - available for completion task type only
  
  microsoft_phi - available for completion task type only
  
  mistral - available for completion task type only
  
  openai - available for text_embedding and completion task types
- rate_limit object
  Hide rate_limit attribute Show rate_limit attribute object
  
  requests_per_minute number
  
  The number of requests allowed per minute.
task_settings object
Hide task_settings attributes Show task_settings attributes object
- do_sample number
  
  For a completion task, instruct the inference process to perform sampling. It has no effect unless temperature or top_p is specified.
- max_new_tokens number
  
  For a completion task, provide a hint for the maximum number of output tokens to be generated.
  
  Default value is 64.
- temperature number
  
  For a completion task, control the apparent creativity of generated completions with a sampling temperature. It must be a number in the range of 0.0 to 2.0. It should not be used if top_p is specified.
- top_p number
  
  For a completion task, make the model consider the results of the tokens with nucleus sampling probability. It is an alternative value to temperature and must be a number in the range of 0.0 to 2.0. It should not be used if temperature is specified.
- user string
  
  For a text_embedding task, specify the user issuing the request. This information can be used for abuse detection.

Responses

200 application/json
Hide response attributes Show response attributes object
- chunking_settings object
  
  Chunking configuration object
  
  Hide chunking_settings attributes Show chunking_settings attributes object
  
  max_chunk_size number
  
  The maximum size of a chunk in words. This value cannot be higher than 300 or lower than 20 (for sentence strategy) or 10 (for word strategy).
  
  Default value is 250.
  
  overlap number
  
  The number of overlapping words for chunks. It is applicable only to a word chunking strategy. This value cannot be higher than half the max_chunk_size value.
  
  Default value is 100.
  
  sentence_overlap number
  
  The number of overlapping sentences for chunks. It is applicable only for a sentence chunking strategy. It can be either 1 or 0.
  
  Default value is 1.
  
  strategy string
  
  The chunking strategy: sentence or word.
  
  Default value is sentence.
- service string Required
  
  The service type
- service_settings object Required
- task_settings object
- inference_id string Required
  
  The inference Id
- task_type string Required
  
  Values are text_embedding or completion.

PUT /_inference/{task_type}/{azureaistudio_inference_id}

PUT _inference/text_embedding/azure_ai_studio_embeddings
{
    "service": "azureaistudio",
    "service_settings": {
        "api_key": "Azure-AI-Studio-API-key",
        "target": "Target-Uri",
        "provider": "openai",
        "endpoint_type": "token"
    }
}

resp = client.inference.put(
    task_type="text_embedding",
    inference_id="azure_ai_studio_embeddings",
    inference_config={
        "service": "azureaistudio",
        "service_settings": {
            "api_key": "Azure-AI-Studio-API-key",
            "target": "Target-Uri",
            "provider": "openai",
            "endpoint_type": "token"
        }
    },
)

const response = await client.inference.put({
  task_type: "text_embedding",
  inference_id: "azure_ai_studio_embeddings",
  inference_config: {
    service: "azureaistudio",
    service_settings: {
      api_key: "Azure-AI-Studio-API-key",
      target: "Target-Uri",
      provider: "openai",
      endpoint_type: "token",
    },
  },
});

response = client.inference.put(
  task_type: "text_embedding",
  inference_id: "azure_ai_studio_embeddings",
  body: {
    "service": "azureaistudio",
    "service_settings": {
      "api_key": "Azure-AI-Studio-API-key",
      "target": "Target-Uri",
      "provider": "openai",
      "endpoint_type": "token"
    }
  }
)

$resp = $client->inference()->put([
    "task_type" => "text_embedding",
    "inference_id" => "azure_ai_studio_embeddings",
    "body" => [
        "service" => "azureaistudio",
        "service_settings" => [
            "api_key" => "Azure-AI-Studio-API-key",
            "target" => "Target-Uri",
            "provider" => "openai",
            "endpoint_type" => "token",
        ],
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"service":"azureaistudio","service_settings":{"api_key":"Azure-AI-Studio-API-key","target":"Target-Uri","provider":"openai","endpoint_type":"token"}}' "$ELASTICSEARCH_URL/_inference/text_embedding/azure_ai_studio_embeddings"

client.inference().put(p -> p
    .inferenceId("azure_ai_studio_embeddings")
    .taskType(TaskType.TextEmbedding)
    .inferenceConfig(i -> i
        .service("azureaistudio")
        .serviceSettings(JsonData.fromJson("{\"api_key\":\"Azure-AI-Studio-API-key\",\"target\":\"Target-Uri\",\"provider\":\"openai\",\"endpoint_type\":\"token\"}"))
    )
);

Request examples

Run `PUT _inference/text_embedding/azure_ai_studio_embeddings` to create an inference endpoint that performs a text_embedding task. Note that you do not specify a model here, as it is defined already in the Azure AI Studio deployment.

{
    "service": "azureaistudio",
    "service_settings": {
        "api_key": "Azure-AI-Studio-API-key",
        "target": "Target-Uri",
        "provider": "openai",
        "endpoint_type": "token"
    }
}

Run `PUT _inference/completion/azure_ai_studio_completion` to create an inference endpoint that performs a completion task.

{
    "service": "azureaistudio",
    "service_settings": {
        "api_key": "Azure-AI-Studio-API-key",
        "target": "Target-URI",
        "provider": "databricks",
        "endpoint_type": "realtime"
    }
}

Create a calendar Generally available; Added in 6.2.0

PUT /_ml/calendars/{calendar_id}

Api key auth Basic auth Bearer auth

Required authorization

Cluster privileges: manage_ml

Path parameters

calendar_id string Required

A string that uniquely identifies a calendar.

application/json

Body

job_ids array[string]

An array of anomaly detection job identifiers.
description string

A description of the calendar.

Responses

200 application/json
Hide response attributes Show response attributes object
- calendar_id string Required
- description string
  
  A description of the calendar.
- job_ids string | array[string] Required
  
  One of:
  Id string array-2 array[string]

PUT /_ml/calendars/{calendar_id}

PUT _ml/calendars/planned-outages

resp = client.ml.put_calendar(
    calendar_id="planned-outages",
)

const response = await client.ml.putCalendar({
  calendar_id: "planned-outages",
});

response = client.ml.put_calendar(
  calendar_id: "planned-outages"
)

$resp = $client->ml()->putCalendar([
    "calendar_id" => "planned-outages",
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/calendars/planned-outages"

client.ml().putCalendar(p -> p
    .calendarId("planned-outages")
);

Get calendar configuration info Generally available; Added in 6.2.0

POST /_ml/calendars/{calendar_id}

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

GET /_ml/calendars

POST /_ml/calendars

GET /_ml/calendars/{calendar_id}

POST /_ml/calendars/{calendar_id}

Required authorization

Cluster privileges: monitor_ml

Path parameters

calendar_id string Required

A string that uniquely identifies a calendar. You can get information for multiple calendars by using a comma-separated list of ids or a wildcard expression. You can get information for all calendars by using _all or * or by omitting the calendar identifier.

Query parameters

from number

Skips the specified number of calendars. This parameter is supported only when you omit the calendar identifier.
size number

Specifies the maximum number of calendars to obtain. This parameter is supported only when you omit the calendar identifier.

application/json

Body

page object
Hide page attributes Show page attributes object
- from number
  
  Skips the specified number of items.
  
  Default value is 0.
- size number
  
  Specifies the maximum number of items to obtain.
  
  Default value is 10000.

Responses

200 application/json
Hide response attributes Show response attributes object
- calendars array[object] Required
  
  Hide calendars attributes Show calendars attributes object
  
  calendar_id string Required
  
  description string
  
  A description of the calendar.
  
  job_ids array[string] Required
  
  An array of anomaly detection job identifiers.
- count number Required

POST /_ml/calendars/{calendar_id}

GET _ml/calendars/planned-outages

resp = client.ml.get_calendars(
    calendar_id="planned-outages",
)

const response = await client.ml.getCalendars({
  calendar_id: "planned-outages",
});

response = client.ml.get_calendars(
  calendar_id: "planned-outages"
)

$resp = $client->ml()->getCalendars([
    "calendar_id" => "planned-outages",
]);

curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_ml/calendars/planned-outages"

client.ml().getCalendars(g -> g
    .calendarId("planned-outages")
);

Create a datafeed Generally available; Added in 5.4.0

PUT /_ml/datafeeds/{datafeed_id}

Api key auth Basic auth Bearer auth

Datafeeds retrieve data from Elasticsearch for analysis by an anomaly detection job. You can associate only one datafeed with each anomaly detection job. The datafeed contains a query that runs at a defined interval (frequency). If you are concerned about delayed data, you can add a delay (query_delay') at each interval. By default, the datafeed uses the following query:{"match_all": {"boost": 1}}`.

When Elasticsearch security features are enabled, your datafeed remembers which roles the user who created it had at the time of creation and runs the query using those same roles. If you provide secondary authorization headers, those credentials are used instead. You must use Kibana, this API, or the create anomaly detection jobs API to create a datafeed. Do not add a datafeed directly to the .ml-config index. Do not give users write privileges on the .ml-config index.

Required authorization

Index privileges: read
Cluster privileges: manage_ml

Path parameters

datafeed_id string Required

A numerical character string that uniquely identifies the datafeed. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start and end with alphanumeric characters.

Query parameters

allow_no_indices boolean

If true, wildcard indices expressions that resolve into no concrete indices are ignored. This includes the _all string or when no indices are specified.
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.

Supported values include:
- all: Match any data stream or index, including hidden ones.
- open: Match open, non-hidden indices. Also matches any non-hidden data stream.
- closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
- hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
- none: Wildcard expressions are not accepted.
Values are all, open, closed, hidden, or none.
ignore_throttled boolean Deprecated

If true, concrete, expanded, or aliased indices are ignored when frozen.
ignore_unavailable boolean

If true, unavailable indices (missing or closed) are ignored.

application/json

Body Required

aggregations object

If set, the datafeed performs aggregation searches. Support for aggregations is limited and should be used only with low cardinality data.
chunking_config object
Hide chunking_config attributes Show chunking_config attributes object
- mode string Required
  
  Values are auto, manual, or off.
- time_span 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.
delayed_data_check_config object
Hide delayed_data_check_config attributes Show delayed_data_check_config attributes object
- check_window 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.
- enabled boolean Required
  
  Specifies whether the datafeed periodically checks for delayed data.
frequency 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 | array[string]
indices_options object

Controls how to deal with unavailable concrete indices (closed or missing), how wildcard expressions are expanded to actual indices (all, closed or open indices) and how to deal with wildcard expressions that resolve to no indices.
Hide indices_options attributes Show indices_options attributes object
- 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. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
- expand_wildcards string | array[string]
- ignore_unavailable boolean
  
  If true, missing or closed indices are not included in the response.
  
  Default value is false.
- ignore_throttled boolean
  
  If true, concrete, expanded or aliased indices are ignored when frozen.
  
  Default value is true.
job_id string
max_empty_searches number

If a real-time datafeed has never seen any data (including during any initial training period), it automatically stops and closes the associated job after this many real-time searches return no documents. In other words, it stops after frequency times max_empty_searches of real-time operation. If not set, a datafeed with no end time that sees no data remains started until it is explicitly stopped. By default, it is not set.
query object

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

External documentation
query_delay 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.
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings 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
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  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.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  string-1 string string-2 string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
script_fields object

Specifies scripts that evaluate custom expressions and returns script fields to the datafeed. The detector configuration objects in a job can contain functions that use these script fields.
Hide script_fields attribute Show script_fields attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  script object Required
  
  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.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  string-1 string string-2 string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  ignore_failure boolean
scroll_size number

The size parameter that is used in Elasticsearch searches when the datafeed does not use aggregations. The maximum value is the value of index.max_result_window, which is 10,000 by default.

Default value is 1000.
headers object

Responses

200 application/json
Hide response attributes Show response attributes object
- aggregations object
- authorization object
  
  Hide authorization attributes Show authorization attributes object
  
  api_key object
  
  Hide api_key attributes Show api_key attributes object
  
  id string Required
  
  The identifier for the API key.
  
  name string Required
  
  The name of the API key.
  
  roles array[string]
  
  If a user ID was used for the most recent update to the datafeed, its roles at the time of the update are listed in the response.
  
  service_account string
  
  If a service account was used for the most recent update to the datafeed, the account name is listed in the response.
- chunking_config object Required
  
  Hide chunking_config attributes Show chunking_config attributes object
  
  mode string Required
  
  Values are auto, manual, or off.
  
  time_span 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.
- delayed_data_check_config object
  
  Hide delayed_data_check_config attributes Show delayed_data_check_config attributes object
  
  check_window 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.
  
  enabled boolean Required
  
  Specifies whether the datafeed periodically checks for delayed data.
- datafeed_id string Required
- frequency 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 array[string] Required
- job_id string Required
- indices_options object
  
  Controls how to deal with unavailable concrete indices (closed or missing), how wildcard expressions are expanded to actual indices (all, closed or open indices) and how to deal with wildcard expressions that resolve to no indices.
  
  Hide indices_options attributes Show indices_options attributes object
  
  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. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
  
  expand_wildcards string | array[string]
  
  ignore_unavailable boolean
  
  If true, missing or closed indices are not included in the response.
  
  Default value is false.
  
  ignore_throttled boolean
  
  If true, concrete, expanded or aliased indices are ignored when frozen.
  
  Default value is true.
- max_empty_searches number
- query object Required
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
- query_delay 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.
- runtime_mappings object
  
  Hide runtime_mappings attribute Show runtime_mappings 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
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  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.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  string-1 string string-2 string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
- script_fields object
  
  Hide script_fields attribute Show script_fields attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  script object Required
  
  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.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  string-1 string string-2 string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  ignore_failure boolean
- scroll_size number Required

PUT /_ml/datafeeds/{datafeed_id}

PUT _ml/datafeeds/datafeed-test-job?pretty
{
  "indices": [
    "kibana_sample_data_logs"
  ],
  "query": {
    "bool": {
      "must": [
        {
          "match_all": {}
        }
      ]
    }
  },
  "job_id": "test-job"
}

resp = client.ml.put_datafeed(
    datafeed_id="datafeed-test-job",
    pretty=True,
    indices=[
        "kibana_sample_data_logs"
    ],
    query={
        "bool": {
            "must": [
                {
                    "match_all": {}
                }
            ]
        }
    },
    job_id="test-job",
)

const response = await client.ml.putDatafeed({
  datafeed_id: "datafeed-test-job",
  pretty: "true",
  indices: ["kibana_sample_data_logs"],
  query: {
    bool: {
      must: [
        {
          match_all: {},
        },
      ],
    },
  },
  job_id: "test-job",
});

response = client.ml.put_datafeed(
  datafeed_id: "datafeed-test-job",
  pretty: "true",
  body: {
    "indices": [
      "kibana_sample_data_logs"
    ],
    "query": {
      "bool": {
        "must": [
          {
            "match_all": {}
          }
        ]
      }
    },
    "job_id": "test-job"
  }
)

$resp = $client->ml()->putDatafeed([
    "datafeed_id" => "datafeed-test-job",
    "pretty" => "true",
    "body" => [
        "indices" => array(
            "kibana_sample_data_logs",
        ),
        "query" => [
            "bool" => [
                "must" => array(
                    [
                        "match_all" => new ArrayObject([]),
                    ],
                ),
            ],
        ],
        "job_id" => "test-job",
    ],
]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"indices":["kibana_sample_data_logs"],"query":{"bool":{"must":[{"match_all":{}}]}},"job_id":"test-job"}' "$ELASTICSEARCH_URL/_ml/datafeeds/datafeed-test-job?pretty"

Request example

An example body for a `PUT _ml/datafeeds/datafeed-test-job?pretty` request.

{
  "indices": [
    "kibana_sample_data_logs"
  ],
  "query": {
    "bool": {
      "must": [
        {
          "match_all": {}
        }
      ]
    }
  },
  "job_id": "test-job"
}

Start datafeeds Generally available; Added in 5.5.0

POST /_ml/datafeeds/{datafeed_id}/_start

Api key auth Basic auth Bearer auth

A datafeed must be started in order to retrieve data from Elasticsearch. A datafeed can be started and stopped multiple times throughout its lifecycle.

Before you can start a datafeed, the anomaly detection job must be open. Otherwise, an error occurs.

If you restart a stopped datafeed, it continues processing input data from the next millisecond after it was stopped. If new data was indexed for that exact millisecond between stopping and starting, it will be ignored.

When Elasticsearch security features are enabled, your datafeed remembers which roles the last user to create or update it had at the time of creation or update and runs the query using those same roles. If you provided secondary authorization headers when you created or updated the datafeed, those credentials are used instead.

Required authorization

Cluster privileges: manage_ml

Path parameters

datafeed_id string Required

A numerical character string that uniquely identifies the datafeed. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start and end with alphanumeric characters.

Query parameters

end string | number
The time that the datafeed should end, which can be specified by using one of the following formats:
- ISO 8601 format with milliseconds, for example 2017-01-22T06:00:00.000Z
- ISO 8601 format without milliseconds, for example 2017-01-22T06:00:00+00:00
- Milliseconds since the epoch, for example 1485061200000
Date-time arguments using either of the ISO 8601 formats must have a time zone designator, where Z is accepted as an abbreviation for UTC time. When a URL is expected (for example, in browsers), the + used in time zone designators must be encoded as %2B. The end time value is exclusive. If you do not specify an end time, the datafeed runs continuously.
start string | number

The time that the datafeed should begin, which can be specified by using the same formats as the end parameter. This value is inclusive. If you do not specify a start time and the datafeed is associated with a new anomaly detection job, the analysis starts from the earliest time for which data is available. If you restart a stopped datafeed and specify a start value that is earlier than the timestamp of the latest processed record, the datafeed continues from 1 millisecond after the timestamp of the latest processed record.
timeout string

Specifies the amount of time to wait until a datafeed starts.

Values are -1 or 0.

application/json

Body

end 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:
string-1 string UnitMillis number
start 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:
string-1 string UnitMillis number
timeout 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.

Responses

200 application/json
Hide response attributes Show response attributes object
- node string | array[string] Required
- started boolean Required
  
  For a successful response, this value is always true. On failure, an exception is returned instead.

POST /_ml/datafeeds/{datafeed_id}/_start

POST _ml/datafeeds/datafeed-low_request_rate/_start
{
  "start": "2019-04-07T18:22:16Z"
}

resp = client.ml.start_datafeed(
    datafeed_id="datafeed-low_request_rate",
    start="2019-04-07T18:22:16Z",
)

const response = await client.ml.startDatafeed({
  datafeed_id: "datafeed-low_request_rate",
  start: "2019-04-07T18:22:16Z",
});

response = client.ml.start_datafeed(
  datafeed_id: "datafeed-low_request_rate",
  body: {
    "start": "2019-04-07T18:22:16Z"
  }
)

$resp = $client->ml()->startDatafeed([
    "datafeed_id" => "datafeed-low_request_rate",
    "body" => [
        "start" => "2019-04-07T18:22:16Z",
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"start":"2019-04-07T18:22:16Z"}' "$ELASTICSEARCH_URL/_ml/datafeeds/datafeed-low_request_rate/_start"

client.ml().startDatafeed(s -> s
    .datafeedId("datafeed-low_request_rate")
    .start(DateTime.of("2019-04-07T18:22:16Z"))
);

Request example

An example body for a `POST _ml/datafeeds/datafeed-low_request_rate/_start` request.

{
  "start": "2019-04-07T18:22:16Z"
}

Create an API key Generally available; Added in 6.7.0

POST /_security/api_key

Api key auth Basic auth Bearer auth

All methods and paths for this operation:

PUT /_security/api_key

POST /_security/api_key

Create an API key for access without requiring basic authentication.

IMPORTANT: If the credential that is used to authenticate this request is an API key, the derived API key cannot have any privileges. If you specify privileges, the API returns an error.

A successful request returns a JSON structure that contains the API key, its unique id, and its name. If applicable, it also returns expiration information for the API key in milliseconds.

NOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.

The API keys are created by the Elasticsearch API key service, which is automatically enabled. To configure or turn off the API key service, refer to API key service setting documentation.

Required authorization

Cluster privileges: manage_own_api_key

External documentation

Query parameters

refresh string

If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

Values are true, false, or wait_for.

application/json

Body Required

expiration 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.
name string
role_descriptors object

An array of role descriptors for this API key. When it is not specified or it is an empty array, the API key will have a point in time snapshot of permissions of the authenticated user. If you supply role descriptors, the resultant permissions are an intersection of API keys permissions and the authenticated user's permissions thereby limiting the access scope for API keys. The structure of role descriptor is the same as the request for the create role API. For more details, refer to the create or update roles API.

NOTE: Due to the way in which this permission intersection is calculated, it is not possible to create an API key that is a child of another API key, unless the derived key is created without any privileges. In this case, you must explicitly specify a role descriptor with no privileges. The derived API key can be used for authentication; it will not have authority to call Elasticsearch APIs.

External documentation
Hide role_descriptors attribute Show role_descriptors attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  cluster array[string]
  
  A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute.
  
  indices array[object]
  
  A list of indices permissions entries.
  
  Hide indices attributes Show indices attributes object
  
  field_security object
  
  Hide field_security attributes Show field_security attributes object
  
  except string | array[string]
  
  grant string | array[string]
  
  names array[string] Required
  
  A list of indices (or index name patterns) to which the permissions in this entry apply.
  
  privileges array[string] Required
  
  The index level privileges that owners of the role have on the specified indices.
  
  query string | object
  
  While creating or updating a role you can provide either a JSON structure or a string to the API. However, the response provided by Elasticsearch will only be string with a json-as-text content.
  
  Since this is embedded in IndicesPrivileges, the same structure is used for clarity in both contexts.
  
  One of:
  string-1 string QueryContainer object RoleTemplateQuery object
  
  allow_restricted_indices boolean Generally available
  
  Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.
  
  Default value is false.
  
  remote_indices array[object] Generally available; Added in 8.14.0
  
  A list of indices permissions for remote clusters.
  
  The subset of index level privileges that can be defined for remote clusters.
  
  Hide remote_indices attributes Show remote_indices attributes object
  
  clusters string | array[string] Required
  
  field_security object
  
  Hide field_security attributes Show field_security attributes object
  
  except string | array[string]
  
  grant string | array[string]
  
  names array[string] Required
  
  A list of indices (or index name patterns) to which the permissions in this entry apply.
  
  privileges array[string] Required
  
  The index level privileges that owners of the role have on the specified indices.
  
  query string | object
  
  While creating or updating a role you can provide either a JSON structure or a string to the API. However, the response provided by Elasticsearch will only be string with a json-as-text content.
  
  Since this is embedded in IndicesPrivileges, the same structure is used for clarity in both contexts.
  
  One of:
  string-1 string QueryContainer object RoleTemplateQuery object
  
  allow_restricted_indices boolean Generally available
  
  Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.
  
  Default value is false.
  
  remote_cluster array[object] Generally available; Added in 8.15.0
  
  A list of cluster permissions for remote clusters. NOTE: This is limited a subset of the cluster permissions.
  
  The subset of cluster level privileges that can be defined for remote clusters.
  
  Hide remote_cluster attributes Show remote_cluster attributes object
  
  clusters string | array[string] Required
  
  privileges array[string] Required
  
  The cluster level privileges that owners of the role have on the remote cluster.
  
  Values are monitor_enrich or monitor_stats.
  
  global array[object] | object
  
  An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware. Support for global privileges is currently limited to the management of application privileges.
  
  One of:
  array-1 array[object] GlobalPrivilege object
  
  Hide attribute Show attribute object
  
  application object Required
  
  Hide application attribute Show application attribute object
  
  manage object Required
  
  Hide attribute Show attribute
  
  application object Required
  
  Hide application attribute Show application attribute object
  
  manage object Required
  
  Hide manage attribute Show manage attribute object
  
  applications array[string] Required
  
  applications array[object]
  
  A list of application privilege entries
  
  Hide applications attributes Show applications attributes object
  
  application string Required
  
  The name of the application to which this entry applies.
  
  privileges array[string] Required
  
  A list of strings, where each element is the name of an application privilege or action.
  
  resources array[string] Required
  
  A list resources to which the privileges are applied.
  
  metadata object
  
  Hide metadata attribute Show metadata attribute object
  
  * object Additional properties
  
  run_as array[string]
  
  A list of users that the API keys can impersonate. NOTE: In Elastic Cloud Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty run_as field, but a non-empty list will be rejected.
  
  description string
  
  Optional description of the role descriptor
  
  restriction object
  
  Hide restriction attribute Show restriction attribute object
  
  workflows array[string] Required
  
  A list of workflows to which the API key is restricted. NOTE: In order to use a role restriction, an API key must be created with a single role descriptor.
  
  transient_metadata object
  
  Hide transient_metadata attribute Show transient_metadata attribute object
  
  * object Additional properties
metadata object
Hide metadata attribute Show metadata attribute object
- * object Additional properties

Responses

200 application/json
Hide response attributes Show response attributes object
- api_key string Required
  
  Generated API key.
- expiration number
  
  Expiration in milliseconds for the API key.
- id string Required
- name string Required
- encoded string Required Generally available; Added in 7.16.0
  
  API key credentials which is the base64-encoding of the UTF-8 representation of id and api_key joined by a colon (:).

POST /_security/api_key

POST /_security/api_key
{
  "name": "my-api-key",
  "expiration": "1d",   
  "role_descriptors": { 
    "role-a": {
      "cluster": ["all"],
      "indices": [
        {
          "names": ["index-a*"],
          "privileges": ["read"]
        }
      ]
    },
    "role-b": {
      "cluster": ["all"],
      "indices": [
        {
          "names": ["index-b*"],
          "privileges": ["all"]
        }
      ]
    }
  },
  "metadata": {
    "application": "my-application",
    "environment": {
      "level": 1,
      "trusted": true,
      "tags": ["dev", "staging"]
    }
  }
}

resp = client.security.create_api_key(
    name="my-api-key",
    expiration="1d",
    role_descriptors={
        "role-a": {
            "cluster": [
                "all"
            ],
            "indices": [
                {
                    "names": [
                        "index-a*"
                    ],
                    "privileges": [
                        "read"
                    ]
                }
            ]
        },
        "role-b": {
            "cluster": [
                "all"
            ],
            "indices": [
                {
                    "names": [
                        "index-b*"
                    ],
                    "privileges": [
                        "all"
                    ]
                }
            ]
        }
    },
    metadata={
        "application": "my-application",
        "environment": {
            "level": 1,
            "trusted": True,
            "tags": [
                "dev",
                "staging"
            ]
        }
    },
)

const response = await client.security.createApiKey({
  name: "my-api-key",
  expiration: "1d",
  role_descriptors: {
    "role-a": {
      cluster: ["all"],
      indices: [
        {
          names: ["index-a*"],
          privileges: ["read"],
        },
      ],
    },
    "role-b": {
      cluster: ["all"],
      indices: [
        {
          names: ["index-b*"],
          privileges: ["all"],
        },
      ],
    },
  },
  metadata: {
    application: "my-application",
    environment: {
      level: 1,
      trusted: true,
      tags: ["dev", "staging"],
    },
  },
});

response = client.security.create_api_key(
  body: {
    "name": "my-api-key",
    "expiration": "1d",
    "role_descriptors": {
      "role-a": {
        "cluster": [
          "all"
        ],
        "indices": [
          {
            "names": [
              "index-a*"
            ],
            "privileges": [
              "read"
            ]
          }
        ]
      },
      "role-b": {
        "cluster": [
          "all"
        ],
        "indices": [
          {
            "names": [
              "index-b*"
            ],
            "privileges": [
              "all"
            ]
          }
        ]
      }
    },
    "metadata": {
      "application": "my-application",
      "environment": {
        "level": 1,
        "trusted": true,
        "tags": [
          "dev",
          "staging"
        ]
      }
    }
  }
)

$resp = $client->security()->createApiKey([
    "body" => [
        "name" => "my-api-key",
        "expiration" => "1d",
        "role_descriptors" => [
            "role-a" => [
                "cluster" => array(
                    "all",
                ),
                "indices" => array(
                    [
                        "names" => array(
                            "index-a*",
                        ),
                        "privileges" => array(
                            "read",
                        ),
                    ],
                ),
            ],
            "role-b" => [
                "cluster" => array(
                    "all",
                ),
                "indices" => array(
                    [
                        "names" => array(
                            "index-b*",
                        ),
                        "privileges" => array(
                            "all",
                        ),
                    ],
                ),
            ],
        ],
        "metadata" => [
            "application" => "my-application",
            "environment" => [
                "level" => 1,
                "trusted" => true,
                "tags" => array(
                    "dev",
                    "staging",
                ),
            ],
        ],
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"name":"my-api-key","expiration":"1d","role_descriptors":{"role-a":{"cluster":["all"],"indices":[{"names":["index-a*"],"privileges":["read"]}]},"role-b":{"cluster":["all"],"indices":[{"names":["index-b*"],"privileges":["all"]}]}},"metadata":{"application":"my-application","environment":{"level":1,"trusted":true,"tags":["dev","staging"]}}}' "$ELASTICSEARCH_URL/_security/api_key"

client.security().createApiKey(c -> c
    .expiration(e -> e
        .time("1d")
    )
    .metadata(Map.of("environment", JsonData.fromJson("{\"level\":1,\"trusted\":true,\"tags\":[\"dev\",\"staging\"]}"),"application", JsonData.fromJson("\"my-application\"")))
    .name("my-api-key")
    .roleDescriptors(Map.of("role-b", RoleDescriptor.of(r -> r
            .cluster("all")
            .indices(i -> i
                .names("index-b*")
                .privileges("all")
            )),"role-a", RoleDescriptor.of(r -> r
            .cluster("all")
            .indices(i -> i
                .names("index-a*")
                .privileges("read")
            ))))
);

Request example

Run `POST /_security/api_key` to create an API key. If `expiration` is not provided, the API keys do not expire. If `role_descriptors` is not provided, the permissions of the authenticated user are applied.

{
  "name": "my-api-key",
  "expiration": "1d",   
  "role_descriptors": { 
    "role-a": {
      "cluster": ["all"],
      "indices": [
        {
          "names": ["index-a*"],
          "privileges": ["read"]
        }
      ]
    },
    "role-b": {
      "cluster": ["all"],
      "indices": [
        {
          "names": ["index-b*"],
          "privileges": ["all"]
        }
      ]
    }
  },
  "metadata": {
    "application": "my-application",
    "environment": {
      "level": 1,
      "trusted": true,
      "tags": ["dev", "staging"]
    }
  }
}

Response examples (200)

A successful response from `POST /_security/api_key`.

{
  "id": "VuaCfGcBCdbkQm-e5aOx",        
  "name": "my-api-key",
  "expiration": 1544068612110,         
  "api_key": "ui2lp2axTNmsyakw9tvNnw", 
  "encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="  
}

Authenticate OpenID Connect Generally available

POST /_security/oidc/authenticate

Api key auth Basic auth Bearer auth

Exchange an OpenID Connect authentication response message for an Elasticsearch internal access token and refresh token that can be subsequently used for authentication.

Elasticsearch exposes all the necessary OpenID Connect related functionality with the OpenID Connect APIs. These APIs are used internally by Kibana in order to provide OpenID Connect based authentication, but can also be used by other, custom web applications or other clients.

application/json

Body Required

nonce string Required

Associate a client session with an ID token and mitigate replay attacks. This value needs to be the same as the one that was provided to the /_security/oidc/prepare API or the one that was generated by Elasticsearch and included in the response to that call.
realm string

The name of the OpenID Connect realm. This property is useful in cases where multiple realms are defined.
redirect_uri string Required

The URL to which the OpenID Connect Provider redirected the User Agent in response to an authentication request after a successful authentication. This URL must be provided as-is (URL encoded), taken from the body of the response or as the value of a location header in the response from the OpenID Connect Provider.
state string Required

Maintain state between the authentication request and the response. This value needs to be the same as the one that was provided to the /_security/oidc/prepare API or the one that was generated by Elasticsearch and included in the response to that call.

Responses

200 application/json
Hide response attributes Show response attributes object
- access_token string Required
  
  The Elasticsearch access token.
- expires_in number Required
  
  The duration (in seconds) of the tokens.
- refresh_token string Required
  
  The Elasticsearch refresh token.
- type string Required
  
  The type of token.

POST /_security/oidc/authenticate

POST /_security/oidc/authenticate
{
  "redirect_uri" : "https://oidc-kibana.elastic.co:5603/api/security/oidc/callback?code=jtI3Ntt8v3_XvcLzCFGq&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
  "state" : "4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
  "nonce" : "WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM",
  "realm" : "oidc1"
}

resp = client.security.oidc_authenticate(
    redirect_uri="https://oidc-kibana.elastic.co:5603/api/security/oidc/callback?code=jtI3Ntt8v3_XvcLzCFGq&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
    state="4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
    nonce="WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM",
    realm="oidc1",
)

const response = await client.security.oidcAuthenticate({
  redirect_uri:
    "https://oidc-kibana.elastic.co:5603/api/security/oidc/callback?code=jtI3Ntt8v3_XvcLzCFGq&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
  state: "4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
  nonce: "WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM",
  realm: "oidc1",
});

response = client.security.oidc_authenticate(
  body: {
    "redirect_uri": "https://oidc-kibana.elastic.co:5603/api/security/oidc/callback?code=jtI3Ntt8v3_XvcLzCFGq&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
    "state": "4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
    "nonce": "WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM",
    "realm": "oidc1"
  }
)

$resp = $client->security()->oidcAuthenticate([
    "body" => [
        "redirect_uri" => "https://oidc-kibana.elastic.co:5603/api/security/oidc/callback?code=jtI3Ntt8v3_XvcLzCFGq&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
        "state" => "4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
        "nonce" => "WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM",
        "realm" => "oidc1",
    ],
]);

curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"redirect_uri":"https://oidc-kibana.elastic.co:5603/api/security/oidc/callback?code=jtI3Ntt8v3_XvcLzCFGq&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I","state":"4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I","nonce":"WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM","realm":"oidc1"}' "$ELASTICSEARCH_URL/_security/oidc/authenticate"

client.security().oidcAuthenticate(o -> o
    .nonce("WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM")
    .realm("oidc1")
    .redirectUri("https://oidc-kibana.elastic.co:5603/api/security/oidc/callback?code=jtI3Ntt8v3_XvcLzCFGq&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I")
    .state("4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I")
);

Request example

Run `POST /_security/oidc/authenticate` to exchange the response that was returned from the OpenID Connect Provider after a successful authentication for an Elasticsearch access token and refresh token. This example is from an authentication that uses the authorization code grant flow.

{
  "redirect_uri" : "https://oidc-kibana.elastic.co:5603/api/security/oidc/callback?code=jtI3Ntt8v3_XvcLzCFGq&state=4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
  "state" : "4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I",
  "nonce" : "WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM",
  "realm" : "oidc1"
}

Response examples (200)

A successful response from `POST /_security/oidc/authenticate`. It contains the access and refresh tokens that were generated, the token duration (in seconds), and the type.

{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200,
  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
}

Delete snapshots Generally available

DELETE /_snapshot/{repository}/{snapshot}

Api key auth Basic auth Bearer auth

Required authorization

Cluster privileges: manage

Path parameters

repository string Required

A repository name
snapshot string Required

A comma-separated list of snapshot names

Query parameters

master_timeout string

Explicit operation timeout for connection to master node

Values are -1 or 0.
wait_for_completion boolean

If true, the request returns a response when the matching snapshots are all deleted. If false, the request returns a response as soon as the deletes are scheduled.

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 /_snapshot/{repository}/{snapshot}

DELETE /_snapshot/my_repository/snapshot_2,snapshot_3

resp = client.snapshot.delete(
    repository="my_repository",
    snapshot="snapshot_2,snapshot_3",
)

const response = await client.snapshot.delete({
  repository: "my_repository",
  snapshot: "snapshot_2,snapshot_3",
});

response = client.snapshot.delete(
  repository: "my_repository",
  snapshot: "snapshot_2,snapshot_3"
)

$resp = $client->snapshot()->delete([
    "repository" => "my_repository",
    "snapshot" => "snapshot_2,snapshot_3",
]);

curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" "$ELASTICSEARCH_URL/_snapshot/my_repository/snapshot_2,snapshot_3"

client.snapshot().delete(d -> d
    .repository("my_repository")
    .snapshot("snapshot_2,snapshot_3")
);

Response examples (200)

A successful response from `DELETE /_snapshot/my_repository/snapshot_2,snapshot_3`. The request deletes `snapshot_2` and `snapshot_3` from the repository named `my_repository`.

{
  "acknowledged" : true
}

Create a behavioral analytics collection Technical preview; Added in 8.8.0

Path parameters

Responses

Compact and aligned text (CAT)

Get the cluster health status Generally available

Required authorization

Query parameters

Responses

epoch number | string

Get node information Generally available

Required authorization

Query parameters

Responses

disk.total number | string

disk.used number | string

disk.avail number | string

disk.used_percent string | number

heap.percent string | number

ram.percent string | number

file_desc.percent string | number

Explain the shard allocations Generally available; Added in 5.0.0

Query parameters

Body

Responses

at string | number Required

Clear the archived repositories metering Technical preview; Added in 7.16.0

Required authorization

Path parameters

Responses

reason string | null

Connector

Update the connector API key ID Beta; Added in 8.12.0

Path parameters

Body Required

Responses

Cross-cluster replication

Delete documents Generally available; Added in 5.0.0

Required authorization

Path parameters

Query parameters

Body Required

Responses

reason string | null

task string | number

Delete an enrich policy Generally available; Added in 7.5.0

Path parameters

Query parameters

Responses

Run an async ES|QL query Generally available; Added in 8.13.0

Required authorization

Query parameters

Body Required

Responses

Index

Check component templates Generally available; Added in 7.8.0

Path parameters

Query parameters

Responses

Move to a lifecycle step Generally available; Added in 6.6.0

Required authorization

Path parameters

Body

Responses

Create an Azure AI studio inference endpoint Generally available; Added in 8.14.0

Required authorization

Path parameters

Query parameters

Body

Responses

Create a calendar Generally available; Added in 6.2.0

Required authorization

Path parameters

Body

Responses

job_ids string | array[string] Required

Get calendar configuration info Generally available; Added in 6.2.0

Required authorization

Path parameters

Query parameters

Body