Get shard allocation information
Get a snapshot of the number of shards allocated to each data node and their disk space.
IMPORTANT: CAT APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications.
Path parameters
-
node_id
string | array[string] Required A comma-separated list of node identifiers or names used to limit the returned information.
Query parameters
-
bytes
string The unit used to display byte values.
Values are
b
,kb
,mb
,gb
,tb
, orpb
. -
h
string | array[string] List of columns to appear in the response. Supports simple wildcards.
-
s
string | array[string] List of columns that determine how the table should be sorted. Sorting defaults to ascending and can be changed by setting
:asc
or:desc
as a suffix to the column name. -
local
boolean If
true
, the request computes the list of selected nodes from the local cluster state. Iffalse
the list of selected nodes are computed from the cluster state of the master node. In both cases the coordinating node will send requests for further information to each selected node. -
master_timeout
string Period to wait for a connection to the master node.
curl \
--request GET 'http://api.example.com/_cat/allocation/{node_id}' \
--header "Authorization: $API_KEY"
[
{
"shards": "1",
"shards.undesired": "0",
"write_load.forecast": "0.0",
"disk.indices.forecast": "260b",
"disk.indices": "260b",
"disk.used": "47.3gb",
"disk.avail": "43.4gb",
"disk.total": "100.7gb",
"disk.percent": "46",
"host": "127.0.0.1",
"ip": "127.0.0.1",
"node": "CSUXak2",
"node.role": "himrst"
}
]
Clear cluster voting config exclusions
Added in 7.0.0
Remove master-eligible nodes from the voting configuration exclusion list.
Query parameters
-
master_timeout
string Period to wait for a connection to the master node.
-
wait_for_removal
boolean Specifies whether to wait for all excluded nodes to be removed from the cluster before clearing the voting configuration exclusions list. Defaults to true, meaning that all excluded nodes must be removed from the cluster before this API takes any action. If set to false then the voting configuration exclusions list is cleared even if some excluded nodes are still in the cluster.
curl \
--request DELETE 'http://api.example.com/_cluster/voting_config_exclusions' \
--header "Authorization: $API_KEY"
Get node statistics
Get statistics for nodes in a cluster. By default, all stats are returned. You can limit the returned information by using metrics.
Path parameters
-
node_id
string | array[string] Required Comma-separated list of node IDs or names used to limit returned information.
Query parameters
-
completion_fields
string | array[string] Comma-separated list or wildcard expressions of fields to include in fielddata and suggest statistics.
-
fielddata_fields
string | array[string] Comma-separated list or wildcard expressions of fields to include in fielddata statistics.
-
fields
string | array[string] Comma-separated list or wildcard expressions of fields to include in the statistics.
-
groups
boolean Comma-separated list of search groups to include in the search statistics.
-
include_segment_file_sizes
boolean If true, the call reports the aggregated disk usage of each one of the Lucene index files (only applies if segment stats are requested).
-
level
string Indicates whether statistics are aggregated at the cluster, index, or shard level.
Values are
cluster
,indices
, orshards
. -
timeout
string Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
-
types
array[string] A comma-separated list of document types for the indexing index metric.
-
include_unloaded_segments
boolean If
true
, the response includes information from segments that are not loaded into memory.
curl \
--request GET 'http://api.example.com/_nodes/{node_id}/stats' \
--header "Authorization: $API_KEY"
{
"_nodes": {
"failures": [
{
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
}
],
"total": 42.0,
"successful": 42.0,
"failed": 42.0
},
"cluster_name": "string",
"nodes": {
"additionalProperty1": {
"adaptive_selection": {
"additionalProperty1": {
"avg_queue_size": 42.0,
"avg_response_time": "string",
"avg_response_time_ns": 42.0,
"avg_service_time": "string",
"avg_service_time_ns": 42.0,
"outgoing_searches": 42.0,
"rank": "string"
},
"additionalProperty2": {
"avg_queue_size": 42.0,
"avg_response_time": "string",
"avg_response_time_ns": 42.0,
"avg_service_time": "string",
"avg_service_time_ns": 42.0,
"outgoing_searches": 42.0,
"rank": "string"
}
},
"breakers": {
"additionalProperty1": {
"estimated_size": "string",
"estimated_size_in_bytes": 42.0,
"limit_size": "string",
"limit_size_in_bytes": 42.0,
"overhead": 42.0,
"tripped": 42.0
},
"additionalProperty2": {
"estimated_size": "string",
"estimated_size_in_bytes": 42.0,
"limit_size": "string",
"limit_size_in_bytes": 42.0,
"overhead": 42.0,
"tripped": 42.0
}
},
"fs": {
"data": [
{}
],
"timestamp": 42.0,
"total": {
"available": "string",
"available_in_bytes": 42.0,
"free": "string",
"free_in_bytes": 42.0,
"total": "string",
"total_in_bytes": 42.0
},
"io_stats": {
"devices": [
{}
],
"total": {}
}
},
"host": "string",
"http": {
"current_open": 42.0,
"total_opened": 42.0,
"clients": [
{}
],
"routes": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"ingest": {
"pipelines": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"total": {
"count": 42.0,
"current": 42.0,
"failed": 42.0
}
},
"ip": "string",
"jvm": {
"buffer_pools": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"classes": {
"current_loaded_count": 42.0,
"total_loaded_count": 42.0,
"total_unloaded_count": 42.0
},
"gc": {
"collectors": {}
},
"mem": {
"heap_used_in_bytes": 42.0,
"heap_used_percent": 42.0,
"heap_committed_in_bytes": 42.0,
"heap_max_in_bytes": 42.0,
"non_heap_used_in_bytes": 42.0,
"non_heap_committed_in_bytes": 42.0,
"pools": {}
},
"threads": {
"count": 42.0,
"peak_count": 42.0
},
"timestamp": 42.0,
"uptime": "string",
"uptime_in_millis": 42.0
},
"name": "string",
"os": {
"cpu": {
"percent": 42.0,
"sys": "string",
"total": "string",
"user": "string",
"load_average": {}
},
"": {},
"swap": {
"adjusted_total_in_bytes": 42.0,
"resident": "string",
"resident_in_bytes": 42.0,
"share": "string",
"share_in_bytes": 42.0,
"total_virtual": "string",
"total_virtual_in_bytes": 42.0,
"total_in_bytes": 42.0,
"free_in_bytes": 42.0,
"used_in_bytes": 42.0
},
"cgroup": {
"cpuacct": {},
"cpu": {},
"memory": {}
},
"timestamp": 42.0
},
"process": {
"cpu": {
"percent": 42.0,
"sys": "string",
"total": "string",
"user": "string",
"load_average": {}
},
"mem": {
"adjusted_total_in_bytes": 42.0,
"resident": "string",
"resident_in_bytes": 42.0,
"share": "string",
"share_in_bytes": 42.0,
"total_virtual": "string",
"total_virtual_in_bytes": 42.0,
"total_in_bytes": 42.0,
"free_in_bytes": 42.0,
"used_in_bytes": 42.0
},
"open_file_descriptors": 42.0,
"max_file_descriptors": 42.0,
"timestamp": 42.0
},
"roles": [
"master"
],
"script": {
"cache_evictions": 42.0,
"compilations": 42.0,
"compilations_history": {
"additionalProperty1": 42.0,
"additionalProperty2": 42.0
},
"compilation_limit_triggered": 42.0,
"contexts": [
{}
]
},
"script_cache": {},
"thread_pool": {
"additionalProperty1": {
"active": 42.0,
"completed": 42.0,
"largest": 42.0,
"queue": 42.0,
"rejected": 42.0,
"threads": 42.0
},
"additionalProperty2": {
"active": 42.0,
"completed": 42.0,
"largest": 42.0,
"queue": 42.0,
"rejected": 42.0,
"threads": 42.0
}
},
"timestamp": 42.0,
"transport": {
"inbound_handling_time_histogram": [
{}
],
"outbound_handling_time_histogram": [
{}
],
"rx_count": 42.0,
"rx_size": "string",
"rx_size_in_bytes": 42.0,
"server_open": 42.0,
"tx_count": 42.0,
"tx_size": "string",
"tx_size_in_bytes": 42.0,
"total_outbound_connections": 42.0
},
"transport_address": "string",
"attributes": {
"additionalProperty1": "string",
"additionalProperty2": "string"
},
"discovery": {
"cluster_state_queue": {
"total": 42.0,
"pending": 42.0,
"committed": 42.0
},
"published_cluster_states": {
"full_states": 42.0,
"incompatible_diffs": 42.0,
"compatible_diffs": 42.0
},
"cluster_state_update": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"serialized_cluster_states": {
"full_states": {},
"diffs": {}
},
"cluster_applier_stats": {
"recordings": [
{}
]
}
},
"indexing_pressure": {
"memory": {
"limit_in_bytes": 42.0,
"current": {},
"total": {}
}
},
"indices": {
"commit": {
"generation": 42.0,
"id": "string",
"num_docs": 42.0,
"user_data": {}
},
"completion": {
"size_in_bytes": 42.0,
"fields": {}
},
"docs": {
"count": 42.0,
"deleted": 42.0
},
"fielddata": {
"evictions": 42.0,
"memory_size_in_bytes": 42.0,
"fields": {}
},
"flush": {
"periodic": 42.0,
"total": 42.0,
"total_time": "string"
},
"get": {
"current": 42.0,
"exists_time": "string",
"exists_total": 42.0,
"missing_time": "string",
"missing_total": 42.0,
"time": "string",
"total": 42.0
},
"indexing": {
"index_current": 42.0,
"delete_current": 42.0,
"delete_time": "string",
"delete_total": 42.0,
"is_throttled": true,
"noop_update_total": 42.0,
"throttle_time": "string",
"index_time": "string",
"index_total": 42.0,
"index_failed": 42.0,
"types": {},
"write_load": 42.0
},
"mappings": {
"total_count": 42.0,
"total_estimated_overhead_in_bytes": 42.0
},
"merges": {
"current": 42.0,
"current_docs": 42.0,
"current_size": "string",
"current_size_in_bytes": 42.0,
"total": 42.0,
"total_auto_throttle": "string",
"total_auto_throttle_in_bytes": 42.0,
"total_docs": 42.0,
"total_size": "string",
"total_size_in_bytes": 42.0,
"total_stopped_time": "string",
"total_throttled_time": "string",
"total_time": "string"
},
"shard_path": {
"data_path": "string",
"is_custom_data_path": true,
"state_path": "string"
},
"query_cache": {
"cache_count": 42.0,
"cache_size": 42.0,
"evictions": 42.0,
"hit_count": 42.0,
"memory_size_in_bytes": 42.0,
"miss_count": 42.0,
"total_count": 42.0
},
"recovery": {
"current_as_source": 42.0,
"current_as_target": 42.0,
"throttle_time": "string"
},
"refresh": {
"external_total": 42.0,
"listeners": 42.0,
"total": 42.0,
"total_time": "string"
},
"request_cache": {
"evictions": 42.0,
"hit_count": 42.0,
"memory_size": "string",
"memory_size_in_bytes": 42.0,
"miss_count": 42.0
},
"retention_leases": {
"primary_term": 42.0,
"version": 42.0,
"leases": [
{}
]
},
"routing": {
"node": "string",
"primary": true,
"state": "UNASSIGNED"
},
"search": {
"fetch_current": 42.0,
"fetch_time": "string",
"fetch_total": 42.0,
"open_contexts": 42.0,
"query_current": 42.0,
"query_time": "string",
"query_total": 42.0,
"scroll_current": 42.0,
"scroll_time": "string",
"scroll_total": 42.0,
"suggest_current": 42.0,
"suggest_time": "string",
"suggest_total": 42.0,
"groups": {}
},
"segments": {
"count": 42.0,
"doc_values_memory_in_bytes": 42.0,
"file_sizes": {},
"fixed_bit_set_memory_in_bytes": 42.0,
"index_writer_max_memory_in_bytes": 42.0,
"index_writer_memory_in_bytes": 42.0,
"max_unsafe_auto_id_timestamp": 42.0,
"memory_in_bytes": 42.0,
"norms_memory_in_bytes": 42.0,
"points_memory_in_bytes": 42.0,
"stored_fields_memory_in_bytes": 42.0,
"terms_memory_in_bytes": 42.0,
"term_vectors_memory_in_bytes": 42.0,
"version_map_memory_in_bytes": 42.0
},
"seq_no": {
"global_checkpoint": 42.0,
"local_checkpoint": 42.0,
"max_seq_no": 42.0
},
"store": {
"size_in_bytes": 42.0,
"reserved_in_bytes": 42.0,
"total_data_set_size_in_bytes": 42.0
},
"translog": {
"earliest_last_modified_age": 42.0,
"operations": 42.0,
"size": "string",
"size_in_bytes": 42.0,
"uncommitted_operations": 42.0,
"uncommitted_size": "string",
"uncommitted_size_in_bytes": 42.0
},
"warmer": {
"current": 42.0,
"total": 42.0,
"total_time": "string"
},
"bulk": {
"total_operations": 42.0,
"total_time": "string",
"total_size_in_bytes": 42.0,
"avg_time": "string",
"avg_size_in_bytes": 42.0
},
"shards": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"shard_stats": {
"total_count": 42.0
},
"additionalProperty1": {
"primaries": {},
"shards": {},
"total": {},
"uuid": "string",
"health": "green",
"status": "open"
},
"additionalProperty2": {
"primaries": {},
"shards": {},
"total": {},
"uuid": "string",
"health": "green",
"status": "open"
}
}
},
"additionalProperty2": {
"adaptive_selection": {
"additionalProperty1": {
"avg_queue_size": 42.0,
"avg_response_time": "string",
"avg_response_time_ns": 42.0,
"avg_service_time": "string",
"avg_service_time_ns": 42.0,
"outgoing_searches": 42.0,
"rank": "string"
},
"additionalProperty2": {
"avg_queue_size": 42.0,
"avg_response_time": "string",
"avg_response_time_ns": 42.0,
"avg_service_time": "string",
"avg_service_time_ns": 42.0,
"outgoing_searches": 42.0,
"rank": "string"
}
},
"breakers": {
"additionalProperty1": {
"estimated_size": "string",
"estimated_size_in_bytes": 42.0,
"limit_size": "string",
"limit_size_in_bytes": 42.0,
"overhead": 42.0,
"tripped": 42.0
},
"additionalProperty2": {
"estimated_size": "string",
"estimated_size_in_bytes": 42.0,
"limit_size": "string",
"limit_size_in_bytes": 42.0,
"overhead": 42.0,
"tripped": 42.0
}
},
"fs": {
"data": [
{}
],
"timestamp": 42.0,
"total": {
"available": "string",
"available_in_bytes": 42.0,
"free": "string",
"free_in_bytes": 42.0,
"total": "string",
"total_in_bytes": 42.0
},
"io_stats": {
"devices": [
{}
],
"total": {}
}
},
"host": "string",
"http": {
"current_open": 42.0,
"total_opened": 42.0,
"clients": [
{}
],
"routes": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"ingest": {
"pipelines": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"total": {
"count": 42.0,
"current": 42.0,
"failed": 42.0
}
},
"ip": "string",
"jvm": {
"buffer_pools": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"classes": {
"current_loaded_count": 42.0,
"total_loaded_count": 42.0,
"total_unloaded_count": 42.0
},
"gc": {
"collectors": {}
},
"mem": {
"heap_used_in_bytes": 42.0,
"heap_used_percent": 42.0,
"heap_committed_in_bytes": 42.0,
"heap_max_in_bytes": 42.0,
"non_heap_used_in_bytes": 42.0,
"non_heap_committed_in_bytes": 42.0,
"pools": {}
},
"threads": {
"count": 42.0,
"peak_count": 42.0
},
"timestamp": 42.0,
"uptime": "string",
"uptime_in_millis": 42.0
},
"name": "string",
"os": {
"cpu": {
"percent": 42.0,
"sys": "string",
"total": "string",
"user": "string",
"load_average": {}
},
"": {},
"swap": {
"adjusted_total_in_bytes": 42.0,
"resident": "string",
"resident_in_bytes": 42.0,
"share": "string",
"share_in_bytes": 42.0,
"total_virtual": "string",
"total_virtual_in_bytes": 42.0,
"total_in_bytes": 42.0,
"free_in_bytes": 42.0,
"used_in_bytes": 42.0
},
"cgroup": {
"cpuacct": {},
"cpu": {},
"memory": {}
},
"timestamp": 42.0
},
"process": {
"cpu": {
"percent": 42.0,
"sys": "string",
"total": "string",
"user": "string",
"load_average": {}
},
"mem": {
"adjusted_total_in_bytes": 42.0,
"resident": "string",
"resident_in_bytes": 42.0,
"share": "string",
"share_in_bytes": 42.0,
"total_virtual": "string",
"total_virtual_in_bytes": 42.0,
"total_in_bytes": 42.0,
"free_in_bytes": 42.0,
"used_in_bytes": 42.0
},
"open_file_descriptors": 42.0,
"max_file_descriptors": 42.0,
"timestamp": 42.0
},
"roles": [
"master"
],
"script": {
"cache_evictions": 42.0,
"compilations": 42.0,
"compilations_history": {
"additionalProperty1": 42.0,
"additionalProperty2": 42.0
},
"compilation_limit_triggered": 42.0,
"contexts": [
{}
]
},
"script_cache": {},
"thread_pool": {
"additionalProperty1": {
"active": 42.0,
"completed": 42.0,
"largest": 42.0,
"queue": 42.0,
"rejected": 42.0,
"threads": 42.0
},
"additionalProperty2": {
"active": 42.0,
"completed": 42.0,
"largest": 42.0,
"queue": 42.0,
"rejected": 42.0,
"threads": 42.0
}
},
"timestamp": 42.0,
"transport": {
"inbound_handling_time_histogram": [
{}
],
"outbound_handling_time_histogram": [
{}
],
"rx_count": 42.0,
"rx_size": "string",
"rx_size_in_bytes": 42.0,
"server_open": 42.0,
"tx_count": 42.0,
"tx_size": "string",
"tx_size_in_bytes": 42.0,
"total_outbound_connections": 42.0
},
"transport_address": "string",
"attributes": {
"additionalProperty1": "string",
"additionalProperty2": "string"
},
"discovery": {
"cluster_state_queue": {
"total": 42.0,
"pending": 42.0,
"committed": 42.0
},
"published_cluster_states": {
"full_states": 42.0,
"incompatible_diffs": 42.0,
"compatible_diffs": 42.0
},
"cluster_state_update": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"serialized_cluster_states": {
"full_states": {},
"diffs": {}
},
"cluster_applier_stats": {
"recordings": [
{}
]
}
},
"indexing_pressure": {
"memory": {
"limit_in_bytes": 42.0,
"current": {},
"total": {}
}
},
"indices": {
"commit": {
"generation": 42.0,
"id": "string",
"num_docs": 42.0,
"user_data": {}
},
"completion": {
"size_in_bytes": 42.0,
"fields": {}
},
"docs": {
"count": 42.0,
"deleted": 42.0
},
"fielddata": {
"evictions": 42.0,
"memory_size_in_bytes": 42.0,
"fields": {}
},
"flush": {
"periodic": 42.0,
"total": 42.0,
"total_time": "string"
},
"get": {
"current": 42.0,
"exists_time": "string",
"exists_total": 42.0,
"missing_time": "string",
"missing_total": 42.0,
"time": "string",
"total": 42.0
},
"indexing": {
"index_current": 42.0,
"delete_current": 42.0,
"delete_time": "string",
"delete_total": 42.0,
"is_throttled": true,
"noop_update_total": 42.0,
"throttle_time": "string",
"index_time": "string",
"index_total": 42.0,
"index_failed": 42.0,
"types": {},
"write_load": 42.0
},
"mappings": {
"total_count": 42.0,
"total_estimated_overhead_in_bytes": 42.0
},
"merges": {
"current": 42.0,
"current_docs": 42.0,
"current_size": "string",
"current_size_in_bytes": 42.0,
"total": 42.0,
"total_auto_throttle": "string",
"total_auto_throttle_in_bytes": 42.0,
"total_docs": 42.0,
"total_size": "string",
"total_size_in_bytes": 42.0,
"total_stopped_time": "string",
"total_throttled_time": "string",
"total_time": "string"
},
"shard_path": {
"data_path": "string",
"is_custom_data_path": true,
"state_path": "string"
},
"query_cache": {
"cache_count": 42.0,
"cache_size": 42.0,
"evictions": 42.0,
"hit_count": 42.0,
"memory_size_in_bytes": 42.0,
"miss_count": 42.0,
"total_count": 42.0
},
"recovery": {
"current_as_source": 42.0,
"current_as_target": 42.0,
"throttle_time": "string"
},
"refresh": {
"external_total": 42.0,
"listeners": 42.0,
"total": 42.0,
"total_time": "string"
},
"request_cache": {
"evictions": 42.0,
"hit_count": 42.0,
"memory_size": "string",
"memory_size_in_bytes": 42.0,
"miss_count": 42.0
},
"retention_leases": {
"primary_term": 42.0,
"version": 42.0,
"leases": [
{}
]
},
"routing": {
"node": "string",
"primary": true,
"state": "UNASSIGNED"
},
"search": {
"fetch_current": 42.0,
"fetch_time": "string",
"fetch_total": 42.0,
"open_contexts": 42.0,
"query_current": 42.0,
"query_time": "string",
"query_total": 42.0,
"scroll_current": 42.0,
"scroll_time": "string",
"scroll_total": 42.0,
"suggest_current": 42.0,
"suggest_time": "string",
"suggest_total": 42.0,
"groups": {}
},
"segments": {
"count": 42.0,
"doc_values_memory_in_bytes": 42.0,
"file_sizes": {},
"fixed_bit_set_memory_in_bytes": 42.0,
"index_writer_max_memory_in_bytes": 42.0,
"index_writer_memory_in_bytes": 42.0,
"max_unsafe_auto_id_timestamp": 42.0,
"memory_in_bytes": 42.0,
"norms_memory_in_bytes": 42.0,
"points_memory_in_bytes": 42.0,
"stored_fields_memory_in_bytes": 42.0,
"terms_memory_in_bytes": 42.0,
"term_vectors_memory_in_bytes": 42.0,
"version_map_memory_in_bytes": 42.0
},
"seq_no": {
"global_checkpoint": 42.0,
"local_checkpoint": 42.0,
"max_seq_no": 42.0
},
"store": {
"size_in_bytes": 42.0,
"reserved_in_bytes": 42.0,
"total_data_set_size_in_bytes": 42.0
},
"translog": {
"earliest_last_modified_age": 42.0,
"operations": 42.0,
"size": "string",
"size_in_bytes": 42.0,
"uncommitted_operations": 42.0,
"uncommitted_size": "string",
"uncommitted_size_in_bytes": 42.0
},
"warmer": {
"current": 42.0,
"total": 42.0,
"total_time": "string"
},
"bulk": {
"total_operations": 42.0,
"total_time": "string",
"total_size_in_bytes": 42.0,
"avg_time": "string",
"avg_size_in_bytes": 42.0
},
"shards": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"shard_stats": {
"total_count": 42.0
},
"additionalProperty1": {
"primaries": {},
"shards": {},
"total": {},
"uuid": "string",
"health": "green",
"status": "open"
},
"additionalProperty2": {
"primaries": {},
"shards": {},
"total": {},
"uuid": "string",
"health": "green",
"status": "open"
}
}
}
}
}
Get node statistics
Get statistics for nodes in a cluster. By default, all stats are returned. You can limit the returned information by using metrics.
Query parameters
-
completion_fields
string | array[string] Comma-separated list or wildcard expressions of fields to include in fielddata and suggest statistics.
-
fielddata_fields
string | array[string] Comma-separated list or wildcard expressions of fields to include in fielddata statistics.
-
fields
string | array[string] Comma-separated list or wildcard expressions of fields to include in the statistics.
-
groups
boolean Comma-separated list of search groups to include in the search statistics.
-
include_segment_file_sizes
boolean If true, the call reports the aggregated disk usage of each one of the Lucene index files (only applies if segment stats are requested).
-
level
string Indicates whether statistics are aggregated at the cluster, index, or shard level.
Values are
cluster
,indices
, orshards
. -
timeout
string Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
-
types
array[string] A comma-separated list of document types for the indexing index metric.
-
include_unloaded_segments
boolean If
true
, the response includes information from segments that are not loaded into memory.
curl \
--request GET 'http://api.example.com/_nodes/{node_id}/stats/{metric}' \
--header "Authorization: $API_KEY"
{
"_nodes": {
"failures": [
{
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
}
],
"total": 42.0,
"successful": 42.0,
"failed": 42.0
},
"cluster_name": "string",
"nodes": {
"additionalProperty1": {
"adaptive_selection": {
"additionalProperty1": {
"avg_queue_size": 42.0,
"avg_response_time": "string",
"avg_response_time_ns": 42.0,
"avg_service_time": "string",
"avg_service_time_ns": 42.0,
"outgoing_searches": 42.0,
"rank": "string"
},
"additionalProperty2": {
"avg_queue_size": 42.0,
"avg_response_time": "string",
"avg_response_time_ns": 42.0,
"avg_service_time": "string",
"avg_service_time_ns": 42.0,
"outgoing_searches": 42.0,
"rank": "string"
}
},
"breakers": {
"additionalProperty1": {
"estimated_size": "string",
"estimated_size_in_bytes": 42.0,
"limit_size": "string",
"limit_size_in_bytes": 42.0,
"overhead": 42.0,
"tripped": 42.0
},
"additionalProperty2": {
"estimated_size": "string",
"estimated_size_in_bytes": 42.0,
"limit_size": "string",
"limit_size_in_bytes": 42.0,
"overhead": 42.0,
"tripped": 42.0
}
},
"fs": {
"data": [
{}
],
"timestamp": 42.0,
"total": {
"available": "string",
"available_in_bytes": 42.0,
"free": "string",
"free_in_bytes": 42.0,
"total": "string",
"total_in_bytes": 42.0
},
"io_stats": {
"devices": [
{}
],
"total": {}
}
},
"host": "string",
"http": {
"current_open": 42.0,
"total_opened": 42.0,
"clients": [
{}
],
"routes": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"ingest": {
"pipelines": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"total": {
"count": 42.0,
"current": 42.0,
"failed": 42.0
}
},
"ip": "string",
"jvm": {
"buffer_pools": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"classes": {
"current_loaded_count": 42.0,
"total_loaded_count": 42.0,
"total_unloaded_count": 42.0
},
"gc": {
"collectors": {}
},
"mem": {
"heap_used_in_bytes": 42.0,
"heap_used_percent": 42.0,
"heap_committed_in_bytes": 42.0,
"heap_max_in_bytes": 42.0,
"non_heap_used_in_bytes": 42.0,
"non_heap_committed_in_bytes": 42.0,
"pools": {}
},
"threads": {
"count": 42.0,
"peak_count": 42.0
},
"timestamp": 42.0,
"uptime": "string",
"uptime_in_millis": 42.0
},
"name": "string",
"os": {
"cpu": {
"percent": 42.0,
"sys": "string",
"total": "string",
"user": "string",
"load_average": {}
},
"": {},
"swap": {
"adjusted_total_in_bytes": 42.0,
"resident": "string",
"resident_in_bytes": 42.0,
"share": "string",
"share_in_bytes": 42.0,
"total_virtual": "string",
"total_virtual_in_bytes": 42.0,
"total_in_bytes": 42.0,
"free_in_bytes": 42.0,
"used_in_bytes": 42.0
},
"cgroup": {
"cpuacct": {},
"cpu": {},
"memory": {}
},
"timestamp": 42.0
},
"process": {
"cpu": {
"percent": 42.0,
"sys": "string",
"total": "string",
"user": "string",
"load_average": {}
},
"mem": {
"adjusted_total_in_bytes": 42.0,
"resident": "string",
"resident_in_bytes": 42.0,
"share": "string",
"share_in_bytes": 42.0,
"total_virtual": "string",
"total_virtual_in_bytes": 42.0,
"total_in_bytes": 42.0,
"free_in_bytes": 42.0,
"used_in_bytes": 42.0
},
"open_file_descriptors": 42.0,
"max_file_descriptors": 42.0,
"timestamp": 42.0
},
"roles": [
"master"
],
"script": {
"cache_evictions": 42.0,
"compilations": 42.0,
"compilations_history": {
"additionalProperty1": 42.0,
"additionalProperty2": 42.0
},
"compilation_limit_triggered": 42.0,
"contexts": [
{}
]
},
"script_cache": {},
"thread_pool": {
"additionalProperty1": {
"active": 42.0,
"completed": 42.0,
"largest": 42.0,
"queue": 42.0,
"rejected": 42.0,
"threads": 42.0
},
"additionalProperty2": {
"active": 42.0,
"completed": 42.0,
"largest": 42.0,
"queue": 42.0,
"rejected": 42.0,
"threads": 42.0
}
},
"timestamp": 42.0,
"transport": {
"inbound_handling_time_histogram": [
{}
],
"outbound_handling_time_histogram": [
{}
],
"rx_count": 42.0,
"rx_size": "string",
"rx_size_in_bytes": 42.0,
"server_open": 42.0,
"tx_count": 42.0,
"tx_size": "string",
"tx_size_in_bytes": 42.0,
"total_outbound_connections": 42.0
},
"transport_address": "string",
"attributes": {
"additionalProperty1": "string",
"additionalProperty2": "string"
},
"discovery": {
"cluster_state_queue": {
"total": 42.0,
"pending": 42.0,
"committed": 42.0
},
"published_cluster_states": {
"full_states": 42.0,
"incompatible_diffs": 42.0,
"compatible_diffs": 42.0
},
"cluster_state_update": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"serialized_cluster_states": {
"full_states": {},
"diffs": {}
},
"cluster_applier_stats": {
"recordings": [
{}
]
}
},
"indexing_pressure": {
"memory": {
"limit_in_bytes": 42.0,
"current": {},
"total": {}
}
},
"indices": {
"commit": {
"generation": 42.0,
"id": "string",
"num_docs": 42.0,
"user_data": {}
},
"completion": {
"size_in_bytes": 42.0,
"fields": {}
},
"docs": {
"count": 42.0,
"deleted": 42.0
},
"fielddata": {
"evictions": 42.0,
"memory_size_in_bytes": 42.0,
"fields": {}
},
"flush": {
"periodic": 42.0,
"total": 42.0,
"total_time": "string"
},
"get": {
"current": 42.0,
"exists_time": "string",
"exists_total": 42.0,
"missing_time": "string",
"missing_total": 42.0,
"time": "string",
"total": 42.0
},
"indexing": {
"index_current": 42.0,
"delete_current": 42.0,
"delete_time": "string",
"delete_total": 42.0,
"is_throttled": true,
"noop_update_total": 42.0,
"throttle_time": "string",
"index_time": "string",
"index_total": 42.0,
"index_failed": 42.0,
"types": {},
"write_load": 42.0
},
"mappings": {
"total_count": 42.0,
"total_estimated_overhead_in_bytes": 42.0
},
"merges": {
"current": 42.0,
"current_docs": 42.0,
"current_size": "string",
"current_size_in_bytes": 42.0,
"total": 42.0,
"total_auto_throttle": "string",
"total_auto_throttle_in_bytes": 42.0,
"total_docs": 42.0,
"total_size": "string",
"total_size_in_bytes": 42.0,
"total_stopped_time": "string",
"total_throttled_time": "string",
"total_time": "string"
},
"shard_path": {
"data_path": "string",
"is_custom_data_path": true,
"state_path": "string"
},
"query_cache": {
"cache_count": 42.0,
"cache_size": 42.0,
"evictions": 42.0,
"hit_count": 42.0,
"memory_size_in_bytes": 42.0,
"miss_count": 42.0,
"total_count": 42.0
},
"recovery": {
"current_as_source": 42.0,
"current_as_target": 42.0,
"throttle_time": "string"
},
"refresh": {
"external_total": 42.0,
"listeners": 42.0,
"total": 42.0,
"total_time": "string"
},
"request_cache": {
"evictions": 42.0,
"hit_count": 42.0,
"memory_size": "string",
"memory_size_in_bytes": 42.0,
"miss_count": 42.0
},
"retention_leases": {
"primary_term": 42.0,
"version": 42.0,
"leases": [
{}
]
},
"routing": {
"node": "string",
"primary": true,
"state": "UNASSIGNED"
},
"search": {
"fetch_current": 42.0,
"fetch_time": "string",
"fetch_total": 42.0,
"open_contexts": 42.0,
"query_current": 42.0,
"query_time": "string",
"query_total": 42.0,
"scroll_current": 42.0,
"scroll_time": "string",
"scroll_total": 42.0,
"suggest_current": 42.0,
"suggest_time": "string",
"suggest_total": 42.0,
"groups": {}
},
"segments": {
"count": 42.0,
"doc_values_memory_in_bytes": 42.0,
"file_sizes": {},
"fixed_bit_set_memory_in_bytes": 42.0,
"index_writer_max_memory_in_bytes": 42.0,
"index_writer_memory_in_bytes": 42.0,
"max_unsafe_auto_id_timestamp": 42.0,
"memory_in_bytes": 42.0,
"norms_memory_in_bytes": 42.0,
"points_memory_in_bytes": 42.0,
"stored_fields_memory_in_bytes": 42.0,
"terms_memory_in_bytes": 42.0,
"term_vectors_memory_in_bytes": 42.0,
"version_map_memory_in_bytes": 42.0
},
"seq_no": {
"global_checkpoint": 42.0,
"local_checkpoint": 42.0,
"max_seq_no": 42.0
},
"store": {
"size_in_bytes": 42.0,
"reserved_in_bytes": 42.0,
"total_data_set_size_in_bytes": 42.0
},
"translog": {
"earliest_last_modified_age": 42.0,
"operations": 42.0,
"size": "string",
"size_in_bytes": 42.0,
"uncommitted_operations": 42.0,
"uncommitted_size": "string",
"uncommitted_size_in_bytes": 42.0
},
"warmer": {
"current": 42.0,
"total": 42.0,
"total_time": "string"
},
"bulk": {
"total_operations": 42.0,
"total_time": "string",
"total_size_in_bytes": 42.0,
"avg_time": "string",
"avg_size_in_bytes": 42.0
},
"shards": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"shard_stats": {
"total_count": 42.0
},
"additionalProperty1": {
"primaries": {},
"shards": {},
"total": {},
"uuid": "string",
"health": "green",
"status": "open"
},
"additionalProperty2": {
"primaries": {},
"shards": {},
"total": {},
"uuid": "string",
"health": "green",
"status": "open"
}
}
},
"additionalProperty2": {
"adaptive_selection": {
"additionalProperty1": {
"avg_queue_size": 42.0,
"avg_response_time": "string",
"avg_response_time_ns": 42.0,
"avg_service_time": "string",
"avg_service_time_ns": 42.0,
"outgoing_searches": 42.0,
"rank": "string"
},
"additionalProperty2": {
"avg_queue_size": 42.0,
"avg_response_time": "string",
"avg_response_time_ns": 42.0,
"avg_service_time": "string",
"avg_service_time_ns": 42.0,
"outgoing_searches": 42.0,
"rank": "string"
}
},
"breakers": {
"additionalProperty1": {
"estimated_size": "string",
"estimated_size_in_bytes": 42.0,
"limit_size": "string",
"limit_size_in_bytes": 42.0,
"overhead": 42.0,
"tripped": 42.0
},
"additionalProperty2": {
"estimated_size": "string",
"estimated_size_in_bytes": 42.0,
"limit_size": "string",
"limit_size_in_bytes": 42.0,
"overhead": 42.0,
"tripped": 42.0
}
},
"fs": {
"data": [
{}
],
"timestamp": 42.0,
"total": {
"available": "string",
"available_in_bytes": 42.0,
"free": "string",
"free_in_bytes": 42.0,
"total": "string",
"total_in_bytes": 42.0
},
"io_stats": {
"devices": [
{}
],
"total": {}
}
},
"host": "string",
"http": {
"current_open": 42.0,
"total_opened": 42.0,
"clients": [
{}
],
"routes": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"ingest": {
"pipelines": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"total": {
"count": 42.0,
"current": 42.0,
"failed": 42.0
}
},
"ip": "string",
"jvm": {
"buffer_pools": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"classes": {
"current_loaded_count": 42.0,
"total_loaded_count": 42.0,
"total_unloaded_count": 42.0
},
"gc": {
"collectors": {}
},
"mem": {
"heap_used_in_bytes": 42.0,
"heap_used_percent": 42.0,
"heap_committed_in_bytes": 42.0,
"heap_max_in_bytes": 42.0,
"non_heap_used_in_bytes": 42.0,
"non_heap_committed_in_bytes": 42.0,
"pools": {}
},
"threads": {
"count": 42.0,
"peak_count": 42.0
},
"timestamp": 42.0,
"uptime": "string",
"uptime_in_millis": 42.0
},
"name": "string",
"os": {
"cpu": {
"percent": 42.0,
"sys": "string",
"total": "string",
"user": "string",
"load_average": {}
},
"": {},
"swap": {
"adjusted_total_in_bytes": 42.0,
"resident": "string",
"resident_in_bytes": 42.0,
"share": "string",
"share_in_bytes": 42.0,
"total_virtual": "string",
"total_virtual_in_bytes": 42.0,
"total_in_bytes": 42.0,
"free_in_bytes": 42.0,
"used_in_bytes": 42.0
},
"cgroup": {
"cpuacct": {},
"cpu": {},
"memory": {}
},
"timestamp": 42.0
},
"process": {
"cpu": {
"percent": 42.0,
"sys": "string",
"total": "string",
"user": "string",
"load_average": {}
},
"mem": {
"adjusted_total_in_bytes": 42.0,
"resident": "string",
"resident_in_bytes": 42.0,
"share": "string",
"share_in_bytes": 42.0,
"total_virtual": "string",
"total_virtual_in_bytes": 42.0,
"total_in_bytes": 42.0,
"free_in_bytes": 42.0,
"used_in_bytes": 42.0
},
"open_file_descriptors": 42.0,
"max_file_descriptors": 42.0,
"timestamp": 42.0
},
"roles": [
"master"
],
"script": {
"cache_evictions": 42.0,
"compilations": 42.0,
"compilations_history": {
"additionalProperty1": 42.0,
"additionalProperty2": 42.0
},
"compilation_limit_triggered": 42.0,
"contexts": [
{}
]
},
"script_cache": {},
"thread_pool": {
"additionalProperty1": {
"active": 42.0,
"completed": 42.0,
"largest": 42.0,
"queue": 42.0,
"rejected": 42.0,
"threads": 42.0
},
"additionalProperty2": {
"active": 42.0,
"completed": 42.0,
"largest": 42.0,
"queue": 42.0,
"rejected": 42.0,
"threads": 42.0
}
},
"timestamp": 42.0,
"transport": {
"inbound_handling_time_histogram": [
{}
],
"outbound_handling_time_histogram": [
{}
],
"rx_count": 42.0,
"rx_size": "string",
"rx_size_in_bytes": 42.0,
"server_open": 42.0,
"tx_count": 42.0,
"tx_size": "string",
"tx_size_in_bytes": 42.0,
"total_outbound_connections": 42.0
},
"transport_address": "string",
"attributes": {
"additionalProperty1": "string",
"additionalProperty2": "string"
},
"discovery": {
"cluster_state_queue": {
"total": 42.0,
"pending": 42.0,
"committed": 42.0
},
"published_cluster_states": {
"full_states": 42.0,
"incompatible_diffs": 42.0,
"compatible_diffs": 42.0
},
"cluster_state_update": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"serialized_cluster_states": {
"full_states": {},
"diffs": {}
},
"cluster_applier_stats": {
"recordings": [
{}
]
}
},
"indexing_pressure": {
"memory": {
"limit_in_bytes": 42.0,
"current": {},
"total": {}
}
},
"indices": {
"commit": {
"generation": 42.0,
"id": "string",
"num_docs": 42.0,
"user_data": {}
},
"completion": {
"size_in_bytes": 42.0,
"fields": {}
},
"docs": {
"count": 42.0,
"deleted": 42.0
},
"fielddata": {
"evictions": 42.0,
"memory_size_in_bytes": 42.0,
"fields": {}
},
"flush": {
"periodic": 42.0,
"total": 42.0,
"total_time": "string"
},
"get": {
"current": 42.0,
"exists_time": "string",
"exists_total": 42.0,
"missing_time": "string",
"missing_total": 42.0,
"time": "string",
"total": 42.0
},
"indexing": {
"index_current": 42.0,
"delete_current": 42.0,
"delete_time": "string",
"delete_total": 42.0,
"is_throttled": true,
"noop_update_total": 42.0,
"throttle_time": "string",
"index_time": "string",
"index_total": 42.0,
"index_failed": 42.0,
"types": {},
"write_load": 42.0
},
"mappings": {
"total_count": 42.0,
"total_estimated_overhead_in_bytes": 42.0
},
"merges": {
"current": 42.0,
"current_docs": 42.0,
"current_size": "string",
"current_size_in_bytes": 42.0,
"total": 42.0,
"total_auto_throttle": "string",
"total_auto_throttle_in_bytes": 42.0,
"total_docs": 42.0,
"total_size": "string",
"total_size_in_bytes": 42.0,
"total_stopped_time": "string",
"total_throttled_time": "string",
"total_time": "string"
},
"shard_path": {
"data_path": "string",
"is_custom_data_path": true,
"state_path": "string"
},
"query_cache": {
"cache_count": 42.0,
"cache_size": 42.0,
"evictions": 42.0,
"hit_count": 42.0,
"memory_size_in_bytes": 42.0,
"miss_count": 42.0,
"total_count": 42.0
},
"recovery": {
"current_as_source": 42.0,
"current_as_target": 42.0,
"throttle_time": "string"
},
"refresh": {
"external_total": 42.0,
"listeners": 42.0,
"total": 42.0,
"total_time": "string"
},
"request_cache": {
"evictions": 42.0,
"hit_count": 42.0,
"memory_size": "string",
"memory_size_in_bytes": 42.0,
"miss_count": 42.0
},
"retention_leases": {
"primary_term": 42.0,
"version": 42.0,
"leases": [
{}
]
},
"routing": {
"node": "string",
"primary": true,
"state": "UNASSIGNED"
},
"search": {
"fetch_current": 42.0,
"fetch_time": "string",
"fetch_total": 42.0,
"open_contexts": 42.0,
"query_current": 42.0,
"query_time": "string",
"query_total": 42.0,
"scroll_current": 42.0,
"scroll_time": "string",
"scroll_total": 42.0,
"suggest_current": 42.0,
"suggest_time": "string",
"suggest_total": 42.0,
"groups": {}
},
"segments": {
"count": 42.0,
"doc_values_memory_in_bytes": 42.0,
"file_sizes": {},
"fixed_bit_set_memory_in_bytes": 42.0,
"index_writer_max_memory_in_bytes": 42.0,
"index_writer_memory_in_bytes": 42.0,
"max_unsafe_auto_id_timestamp": 42.0,
"memory_in_bytes": 42.0,
"norms_memory_in_bytes": 42.0,
"points_memory_in_bytes": 42.0,
"stored_fields_memory_in_bytes": 42.0,
"terms_memory_in_bytes": 42.0,
"term_vectors_memory_in_bytes": 42.0,
"version_map_memory_in_bytes": 42.0
},
"seq_no": {
"global_checkpoint": 42.0,
"local_checkpoint": 42.0,
"max_seq_no": 42.0
},
"store": {
"size_in_bytes": 42.0,
"reserved_in_bytes": 42.0,
"total_data_set_size_in_bytes": 42.0
},
"translog": {
"earliest_last_modified_age": 42.0,
"operations": 42.0,
"size": "string",
"size_in_bytes": 42.0,
"uncommitted_operations": 42.0,
"uncommitted_size": "string",
"uncommitted_size_in_bytes": 42.0
},
"warmer": {
"current": 42.0,
"total": 42.0,
"total_time": "string"
},
"bulk": {
"total_operations": 42.0,
"total_time": "string",
"total_size_in_bytes": 42.0,
"avg_time": "string",
"avg_size_in_bytes": 42.0
},
"shards": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"shard_stats": {
"total_count": 42.0
},
"additionalProperty1": {
"primaries": {},
"shards": {},
"total": {},
"uuid": "string",
"health": "green",
"status": "open"
},
"additionalProperty2": {
"primaries": {},
"shards": {},
"total": {},
"uuid": "string",
"health": "green",
"status": "open"
}
}
}
}
}
Query parameters
-
timeout
string Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request GET 'http://api.example.com/_nodes/usage' \
--header "Authorization: $API_KEY"
{
"_nodes": {
"failures": [
{
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
}
],
"total": 42.0,
"successful": 42.0,
"failed": 42.0
},
"cluster_name": "string",
"nodes": {
"additionalProperty1": {
"rest_actions": {
"additionalProperty1": 42.0,
"additionalProperty2": 42.0
},
"": 42.0,
"aggregations": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"additionalProperty2": {
"rest_actions": {
"additionalProperty1": 42.0,
"additionalProperty2": 42.0
},
"": 42.0,
"aggregations": {
"additionalProperty1": {},
"additionalProperty2": {}
}
}
}
}
Check for a document source
Added in 5.4.0
Check whether a document source exists in an index. For example:
HEAD my-index-000001/_source/1
A document's source is not available if it is disabled in the mapping.
Query parameters
-
preference
string The node or shard the operation should be performed on. By default, the operation is randomized between the shard replicas.
-
realtime
boolean If
true
, the request is real-time as opposed to near-real-time. -
refresh
boolean If
true
, the request refreshes the relevant shards before retrieving the document. Setting it totrue
should be done after careful thought and verification that this does not cause a heavy load on the system (and slow down indexing). -
routing
string A custom value used to route operations to a specific shard.
-
_source
boolean | string | array[string] Indicates whether to return the
_source
field (true
orfalse
) or lists the fields to return. -
_source_excludes
string | array[string] A comma-separated list of source fields to exclude in the response.
-
_source_includes
string | array[string] A comma-separated list of source fields to include in the response.
-
version
number The version number for concurrency control. It must match the current version of the document for the request to succeed.
-
version_type
string The version type.
Values are
internal
,external
,external_gte
, orforce
.
curl \
--request HEAD 'http://api.example.com/{index}/_source/{id}' \
--header "Authorization: $API_KEY"
Create or update a document in an index
Add a JSON document to the specified data stream or index and make it searchable. If the target is an index and the document already exists, the request updates the document and increments its version.
NOTE: You cannot use this API to send update requests for existing documents in a data stream.
If the Elasticsearch security features are enabled, you must have the following index privileges for the target data stream, index, or index alias:
- To add or overwrite a document using the
PUT /<target>/_doc/<_id>
request format, you must have thecreate
,index
, orwrite
index privilege. - To add a document using the
POST /<target>/_doc/
request format, you must have thecreate_doc
,create
,index
, orwrite
index privilege. - To automatically create a data stream or index with this API request, you must have the
auto_configure
,create_index
, ormanage
index privilege.
Automatic data stream creation requires a matching index template with data stream enabled.
NOTE: Replica shards might not all be started when an indexing operation returns successfully.
By default, only the primary is required. Set wait_for_active_shards
to change this default behavior.
Automatically create data streams and indices
If the request's target doesn't exist and matches an index template with a data_stream
definition, the index operation automatically creates the data stream.
If the target doesn't exist and doesn't match a data stream template, the operation automatically creates the index and applies any matching index templates.
NOTE: Elasticsearch includes several built-in index templates. To avoid naming collisions with these templates, refer to index pattern documentation.
If no mapping exists, the index operation creates a dynamic mapping. By default, new fields and objects are automatically added to the mapping if needed.
Automatic index creation is controlled by the action.auto_create_index
setting.
If it is true
, any index can be created automatically.
You can modify this setting to explicitly allow or block automatic creation of indices that match specified patterns or set it to false
to turn off automatic index creation entirely.
Specify a comma-separated list of patterns you want to allow or prefix each pattern with +
or -
to indicate whether it should be allowed or blocked.
When a list is specified, the default behaviour is to disallow.
NOTE: The action.auto_create_index
setting affects the automatic creation of indices only.
It does not affect the creation of data streams.
Optimistic concurrency control
Index operations can be made conditional and only be performed if the last modification to the document was assigned the sequence number and primary term specified by the if_seq_no
and if_primary_term
parameters.
If a mismatch is detected, the operation will result in a VersionConflictException
and a status code of 409
.
Routing
By default, shard placement — or routing — is controlled by using a hash of the document's ID value.
For more explicit control, the value fed into the hash function used by the router can be directly specified on a per-operation basis using the routing
parameter.
When setting up explicit mapping, you can also use the _routing
field to direct the index operation to extract the routing value from the document itself.
This does come at the (very minimal) cost of an additional document parsing pass.
If the _routing
mapping is defined and set to be required, the index operation will fail if no routing value is provided or extracted.
NOTE: Data streams do not support custom routing unless they were created with the allow_custom_routing
setting enabled in the template.
Distributed
The index operation is directed to the primary shard based on its route and performed on the actual node containing this shard. After the primary shard completes the operation, if needed, the update is distributed to applicable replicas.
Active shards
To improve the resiliency of writes to the system, indexing operations can be configured to wait for a certain number of active shard copies before proceeding with the operation.
If the requisite number of active shard copies are not available, then the write operation must wait and retry, until either the requisite shard copies have started or a timeout occurs.
By default, write operations only wait for the primary shards to be active before proceeding (that is to say wait_for_active_shards
is 1
).
This default can be overridden in the index settings dynamically by setting index.write.wait_for_active_shards
.
To alter this behavior per operation, use the wait_for_active_shards request
parameter.
Valid values are all or any positive integer up to the total number of configured copies per shard in the index (which is number_of_replicas
+1).
Specifying a negative value or a number greater than the number of shard copies will throw an error.
For example, suppose you have a cluster of three nodes, A, B, and C and you create an index index with the number of replicas set to 3 (resulting in 4 shard copies, one more copy than there are nodes).
If you attempt an indexing operation, by default the operation will only ensure the primary copy of each shard is available before proceeding.
This means that even if B and C went down and A hosted the primary shard copies, the indexing operation would still proceed with only one copy of the data.
If wait_for_active_shards
is set on the request to 3
(and all three nodes are up), the indexing operation will require 3 active shard copies before proceeding.
This requirement should be met because there are 3 active nodes in the cluster, each one holding a copy of the shard.
However, if you set wait_for_active_shards
to all
(or to 4
, which is the same in this situation), the indexing operation will not proceed as you do not have all 4 copies of each shard active in the index.
The operation will timeout unless a new node is brought up in the cluster to host the fourth copy of the shard.
It is important to note that this setting greatly reduces the chances of the write operation not writing to the requisite number of shard copies, but it does not completely eliminate the possibility, because this check occurs before the write operation starts.
After the write operation is underway, it is still possible for replication to fail on any number of shard copies but still succeed on the primary.
The _shards
section of the API response reveals the number of shard copies on which replication succeeded and failed.
No operation (noop) updates
When updating a document by using this API, a new version of the document is always created even if the document hasn't changed.
If this isn't acceptable use the _update
API with detect_noop
set to true
.
The detect_noop
option isn't available on this API because it doesn’t fetch the old source and isn't able to compare it against the new source.
There isn't a definitive rule for when noop updates aren't acceptable. It's a combination of lots of factors like how frequently your data source sends updates that are actually noops and how many queries per second Elasticsearch runs on the shard receiving the updates.
Versioning
Each indexed document is given a version number.
By default, internal versioning is used that starts at 1 and increments with each update, deletes included.
Optionally, the version number can be set to an external value (for example, if maintained in a database).
To enable this functionality, version_type
should be set to external
.
The value provided must be a numeric, long value greater than or equal to 0, and less than around 9.2e+18
.
NOTE: Versioning is completely real time, and is not affected by the near real time aspects of search operations. If no version is provided, the operation runs without any version checks.
When using the external version type, the system checks to see if the version number passed to the index request is greater than the version of the currently stored document. If true, the document will be indexed and the new version number used. If the value provided is less than or equal to the stored document's version number, a version conflict will occur and the index operation will fail. For example:
PUT my-index-000001/_doc/1?version=2&version_type=external
{
"user": {
"id": "elkbee"
}
}
In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1.
If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).
A nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used.
Even the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.
Path parameters
-
index
string Required The name of the data stream or index to target. If the target doesn't exist and matches the name or wildcard (
*
) pattern of an index template with adata_stream
definition, this request creates the data stream. If the target doesn't exist and doesn't match a data stream template, this request creates the index. You can check for existing targets with the resolve index API.
Query parameters
-
if_primary_term
number Only perform the operation if the document has this primary term.
-
if_seq_no
number Only perform the operation if the document has this sequence number.
-
include_source_on_error
boolean True or false if to include the document source in the error message in case of parsing errors.
-
op_type
string Set to
create
to only index the document if it does not already exist (put if absent). If a document with the specified_id
already exists, the indexing operation will fail. The behavior is the same as using the<index>/_create
endpoint. If a document ID is specified, this paramater defaults toindex
. Otherwise, it defaults tocreate
. If the request targets a data stream, anop_type
ofcreate
is required.Values are
index
orcreate
. -
pipeline
string The ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to
_none
disables the default ingest pipeline for this request. If a final pipeline is configured it will always run, regardless of the value of this parameter. -
refresh
string If
true
, Elasticsearch refreshes the affected shards to make this operation visible to search. Ifwait_for
, it waits for a refresh to make this operation visible to search. Iffalse
, it does nothing with refreshes.Values are
true
,false
, orwait_for
. -
routing
string A custom value that is used to route operations to a specific shard.
-
timeout
string The period the request waits for the following operations: automatic index creation, dynamic mapping updates, waiting for active shards.
This parameter is useful for situations where the primary shard assigned to perform the operation might not be available when the operation runs. Some reasons for this might be that the primary shard is currently recovering from a gateway or undergoing relocation. By default, the operation will wait on the primary shard to become available for at least 1 minute before failing and responding with an error. The actual wait time could be longer, particularly when multiple waits occur.
-
version
number An explicit version number for concurrency control. It must be a non-negative long number.
-
version_type
string The version type.
Values are
internal
,external
,external_gte
, orforce
. -
wait_for_active_shards
number | string The number of shard copies that must be active before proceeding with the operation. You can set it to
all
or any positive integer up to the total number of shards in the index (number_of_replicas+1
). The default value of1
means it waits for each primary shard to be active. -
require_alias
boolean If
true
, the destination must be an index alias.
curl \
--request POST 'http://api.example.com/{index}/_doc' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"@timestamp\": \"2099-11-15T13:12:00\",\n \"message\": \"GET /search HTTP/1.1 200 1070000\",\n \"user\": {\n \"id\": \"kimchy\"\n }\n}"'
{
"@timestamp": "2099-11-15T13:12:00",
"message": "GET /search HTTP/1.1 200 1070000",
"user": {
"id": "kimchy"
}
}
{
"@timestamp": "2099-11-15T13:12:00",
"message": "GET /search HTTP/1.1 200 1070000",
"user": {
"id": "kimchy"
}
}
{
"_shards": {
"total": 2,
"failed": 0,
"successful": 2
},
"_index": "my-index-000001",
"_id": "W0tpsmIBdwcYyG50zbta",
"_version": 1,
"_seq_no": 0,
"_primary_term": 1,
"result": "created"
}
{
"_shards": {
"total": 2,
"failed": 0,
"successful": 2
},
"_index": "my-index-000001",
"_id": "1",
"_version": 1,
"_seq_no": 0,
"_primary_term": 1,
"result": "created"
}
Get multiple term vectors
Get multiple term vectors with a single request.
You can specify existing documents by index and ID or provide artificial documents in the body of the request.
You can specify the index in the request body or request URI.
The response contains a docs
array with all the fetched termvectors.
Each element has the structure provided by the termvectors API.
Artificial documents
You can also use mtermvectors
to generate term vectors for artificial documents provided in the body of the request.
The mapping used is determined by the specified _index
.
Path parameters
-
index
string Required The name of the index that contains the documents.
Query parameters
-
ids
array[string] A comma-separated list of documents ids. You must define ids as parameter or set "ids" or "docs" in the request body
-
fields
string | array[string] A comma-separated list or wildcard expressions of fields to include in the statistics. It is used as the default list unless a specific field list is provided in the
completion_fields
orfielddata_fields
parameters. -
field_statistics
boolean If
true
, the response includes the document count, sum of document frequencies, and sum of total term frequencies. -
offsets
boolean If
true
, the response includes term offsets. -
payloads
boolean If
true
, the response includes term payloads. -
positions
boolean If
true
, the response includes term positions. -
preference
string The node or shard the operation should be performed on. It is random by default.
-
realtime
boolean If true, the request is real-time as opposed to near-real-time.
-
routing
string A custom value used to route operations to a specific shard.
-
term_statistics
boolean If true, the response includes term frequency and document frequency.
-
version
number If
true
, returns the document version as part of a hit. -
version_type
string The version type.
Values are
internal
,external
,external_gte
, orforce
.
curl \
--request GET 'http://api.example.com/{index}/_mtermvectors' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"docs\": [\n {\n \"_id\": \"2\",\n \"fields\": [\n \"message\"\n ],\n \"term_statistics\": true\n },\n {\n \"_id\": \"1\"\n }\n ]\n}"'
{
"docs": [
{
"_id": "2",
"fields": [
"message"
],
"term_statistics": true
},
{
"_id": "1"
}
]
}
{
"ids": [ "1", "2" ],
"fields": [
"message"
],
"term_statistics": true
}
{
"docs": [
{
"_index": "my-index-000001",
"doc" : {
"message" : "test test test"
}
},
{
"_index": "my-index-000001",
"doc" : {
"message" : "Another test ..."
}
}
]
}
{
"docs": [
{
"_id": "string",
"_index": "string",
"_version": 42.0,
"took": 42.0,
"found": true,
"term_vectors": {
"additionalProperty1": {
"field_statistics": {
"doc_count": 42.0,
"sum_doc_freq": 42.0,
"sum_ttf": 42.0
},
"terms": {
"additionalProperty1": {},
"additionalProperty2": {}
}
},
"additionalProperty2": {
"field_statistics": {
"doc_count": 42.0,
"sum_doc_freq": 42.0,
"sum_ttf": 42.0
},
"terms": {
"additionalProperty1": {},
"additionalProperty2": {}
}
}
},
"error": {
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
}
}
]
}
Get index templates
Added in 7.9.0
Get information about one or more index templates.
Query parameters
-
local
boolean If true, the request retrieves information from the local node only. Defaults to false, which means information is retrieved from the master node.
-
flat_settings
boolean If true, returns settings in flat format.
-
master_timeout
string Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
-
include_defaults
boolean If true, returns all relevant default configurations for the index template.
curl \
--request GET 'http://api.example.com/_index_template' \
--header "Authorization: $API_KEY"
{
"index_templates": [
{
"name": "string",
"index_template": {
"index_patterns": "string",
"composed_of": [
"string"
],
"template": {
"aliases": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"mappings": {
"all_field": {},
"date_detection": true,
"dynamic": "strict",
"dynamic_date_formats": [
"string"
],
"dynamic_templates": [
{}
],
"_field_names": {},
"index_field": {},
"_meta": {},
"numeric_detection": true,
"properties": {},
"_routing": {},
"_size": {},
"_source": {},
"runtime": {},
"enabled": true,
"subobjects": "true",
"_data_stream_timestamp": {}
},
"settings": {
"index": {},
"mode": "string",
"soft_deletes": {},
"sort": {},
"number_of_routing_shards": 42.0,
"check_on_startup": "true",
"codec": "string",
"load_fixed_bitset_filters_eagerly": true,
"merge": {},
"search": {},
"refresh_interval": "string",
"max_result_window": 42.0,
"max_inner_result_window": 42.0,
"max_rescore_window": 42.0,
"max_docvalue_fields_search": 42.0,
"max_script_fields": 42.0,
"max_ngram_diff": 42.0,
"max_shingle_diff": 42.0,
"blocks": {},
"max_refresh_listeners": 42.0,
"analyze": {},
"highlight": {},
"max_terms_count": 42.0,
"max_regex_length": 42.0,
"routing": {},
"gc_deletes": "string",
"default_pipeline": "string",
"final_pipeline": "string",
"lifecycle": {},
"provided_name": "string",
"uuid": "string",
"version": {},
"max_slices_per_scroll": 42.0,
"translog": {},
"query_string": {},
"top_metrics_max_size": 42.0,
"analysis": {},
"settings": {},
"time_series": {},
"queries": {},
"similarity": {},
"mapping": {},
"indexing.slowlog": {},
"indexing_pressure": {},
"store": {}
},
"": {}
},
"version": 42.0,
"priority": 42.0,
"_meta": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"allow_auto_create": true,
"data_stream": {
"hidden": true,
"allow_custom_routing": true
},
"deprecated": true,
"ignore_missing_component_templates": "string"
}
}
]
}
Get index settings
Get setting information for one or more indices. For data streams, it returns setting information for the stream's backing indices.
Path parameters
-
index
string | array[string] Required Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (
*
). To target all data streams and indices, omit this parameter or use*
or_all
.
Query parameters
-
allow_no_indices
boolean If
false
, the request returns an error if any wildcard expression, index alias, or_all
value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targetingfoo*,bar*
returns an error if an index starts with foo but no index starts withbar
. -
expand_wildcards
string | array[string] Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as
open,hidden
. -
flat_settings
boolean If
true
, returns settings in flat format. -
include_defaults
boolean If
true
, return all default settings in the response. -
local
boolean If
true
, the request retrieves information from the local node only. Iffalse
, information is retrieved from the master node. -
master_timeout
string Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
curl \
--request GET 'http://api.example.com/{index}/_settings' \
--header "Authorization: $API_KEY"
{
"*": {
"aliases": {
"additionalProperty1": {
"filter": {},
"index_routing": "string",
"is_hidden": true,
"is_write_index": true,
"routing": "string",
"search_routing": "string"
},
"additionalProperty2": {
"filter": {},
"index_routing": "string",
"is_hidden": true,
"is_write_index": true,
"routing": "string",
"search_routing": "string"
}
},
"mappings": {
"all_field": {
"analyzer": "string",
"enabled": true,
"omit_norms": true,
"search_analyzer": "string",
"similarity": "string",
"store": true,
"store_term_vector_offsets": true,
"store_term_vector_payloads": true,
"store_term_vector_positions": true,
"store_term_vectors": true
},
"date_detection": true,
"dynamic": "strict",
"dynamic_date_formats": [
"string"
],
"dynamic_templates": [
{}
],
"_field_names": {
"enabled": true
},
"index_field": {
"enabled": true
},
"_meta": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"numeric_detection": true,
"properties": {},
"_routing": {
"required": true
},
"_size": {
"enabled": true
},
"_source": {
"compress": true,
"compress_threshold": "string",
"enabled": true,
"excludes": [
"string"
],
"includes": [
"string"
],
"mode": "disabled"
},
"runtime": {
"additionalProperty1": {
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"fetch_fields": [
{}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {
"source": "string",
"id": "string",
"params": {},
"options": {}
},
"type": "boolean"
},
"additionalProperty2": {
"fields": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"fetch_fields": [
{}
],
"format": "string",
"input_field": "string",
"target_field": "string",
"target_index": "string",
"script": {
"source": "string",
"id": "string",
"params": {},
"options": {}
},
"type": "boolean"
}
},
"enabled": true,
"subobjects": "true",
"_data_stream_timestamp": {
"enabled": true
}
},
"settings": {
"index": {},
"mode": "string",
"routing_path": "string",
"soft_deletes": {
"enabled": true,
"retention_lease": {
"period": "string"
}
},
"sort": {
"field": "string",
"order": "asc",
"mode": "min",
"missing": "_last"
},
"number_of_shards": 42.0,
"number_of_replicas": 42.0,
"number_of_routing_shards": 42.0,
"check_on_startup": "true",
"codec": "string",
"": "string",
"load_fixed_bitset_filters_eagerly": true,
"hidden": true,
"auto_expand_replicas": "string",
"merge": {
"scheduler": {
"": 42.0
}
},
"search": {
"idle": {
"after": "string"
},
"slowlog": {
"level": "string",
"source": 42.0,
"reformat": true,
"threshold": {
"query": {},
"fetch": {}
}
}
},
"refresh_interval": "string",
"max_result_window": 42.0,
"max_inner_result_window": 42.0,
"max_rescore_window": 42.0,
"max_docvalue_fields_search": 42.0,
"max_script_fields": 42.0,
"max_ngram_diff": 42.0,
"max_shingle_diff": 42.0,
"blocks": {
"": true
},
"max_refresh_listeners": 42.0,
"analyze": {
"": 42.0
},
"highlight": {
"max_analyzed_offset": 42.0
},
"max_terms_count": 42.0,
"max_regex_length": 42.0,
"routing": {
"allocation": {
"enable": "all",
"include": {
"_tier_preference": "string",
"_id": "string"
},
"initial_recovery": {
"_id": "string"
},
"disk": {}
},
"rebalance": {
"enable": "all"
}
},
"gc_deletes": "string",
"default_pipeline": "string",
"final_pipeline": "string",
"lifecycle": {
"name": "string",
"": true,
"origination_date": 42.0,
"parse_origination_date": true,
"step": {
"wait_time_threshold": "string"
},
"rollover_alias": "string",
"prefer_ilm": true
},
"provided_name": "string",
"uuid": "string",
"version": {
"created": "string",
"created_string": "string"
},
"verified_before_close": true,
"format": "string",
"max_slices_per_scroll": 42.0,
"translog": {
"sync_interval": "string",
"durability": "request",
"": 42.0,
"retention": {
"": 42.0,
"age": "string"
}
},
"query_string": {
"": true
},
"priority": 42.0,
"top_metrics_max_size": 42.0,
"analysis": {
"analyzer": {},
"char_filter": {},
"filter": {},
"normalizer": {},
"tokenizer": {}
},
"settings": {},
"time_series": {
"": "string"
},
"queries": {
"cache": {
"enabled": true
}
},
"similarity": {},
"mapping": {
"coerce": true,
"total_fields": {
"limit": 42.0,
"ignore_dynamic_beyond_limit": true
},
"depth": {
"limit": 42.0
},
"nested_fields": {
"limit": 42.0
},
"nested_objects": {
"limit": 42.0
},
"field_name_length": {
"limit": 42.0
},
"dimension_fields": {
"limit": 42.0
},
"source": {
"mode": "disabled"
},
"ignore_malformed": true
},
"indexing.slowlog": {
"level": "string",
"source": 42.0,
"reformat": true,
"threshold": {
"index": {
"warn": "string",
"info": "string",
"debug": "string",
"trace": "string"
}
}
},
"indexing_pressure": {
"memory": {
"limit": 42.0
}
},
"store": {
"": "fs",
"allow_mmap": true
}
},
"defaults": {
"index": {},
"mode": "string",
"routing_path": "string",
"soft_deletes": {
"enabled": true,
"retention_lease": {
"period": "string"
}
},
"sort": {
"field": "string",
"order": "asc",
"mode": "min",
"missing": "_last"
},
"number_of_shards": 42.0,
"number_of_replicas": 42.0,
"number_of_routing_shards": 42.0,
"check_on_startup": "true",
"codec": "string",
"": "string",
"load_fixed_bitset_filters_eagerly": true,
"hidden": true,
"auto_expand_replicas": "string",
"merge": {
"scheduler": {
"": 42.0
}
},
"search": {
"idle": {
"after": "string"
},
"slowlog": {
"level": "string",
"source": 42.0,
"reformat": true,
"threshold": {
"query": {},
"fetch": {}
}
}
},
"refresh_interval": "string",
"max_result_window": 42.0,
"max_inner_result_window": 42.0,
"max_rescore_window": 42.0,
"max_docvalue_fields_search": 42.0,
"max_script_fields": 42.0,
"max_ngram_diff": 42.0,
"max_shingle_diff": 42.0,
"blocks": {
"": true
},
"max_refresh_listeners": 42.0,
"analyze": {
"": 42.0
},
"highlight": {
"max_analyzed_offset": 42.0
},
"max_terms_count": 42.0,
"max_regex_length": 42.0,
"routing": {
"allocation": {
"enable": "all",
"include": {
"_tier_preference": "string",
"_id": "string"
},
"initial_recovery": {
"_id": "string"
},
"disk": {}
},
"rebalance": {
"enable": "all"
}
},
"gc_deletes": "string",
"default_pipeline": "string",
"final_pipeline": "string",
"lifecycle": {
"name": "string",
"": true,
"origination_date": 42.0,
"parse_origination_date": true,
"step": {
"wait_time_threshold": "string"
},
"rollover_alias": "string",
"prefer_ilm": true
},
"provided_name": "string",
"uuid": "string",
"version": {
"created": "string",
"created_string": "string"
},
"verified_before_close": true,
"format": "string",
"max_slices_per_scroll": 42.0,
"translog": {
"sync_interval": "string",
"durability": "request",
"": 42.0,
"retention": {
"": 42.0,
"age": "string"
}
},
"query_string": {
"": true
},
"priority": 42.0,
"top_metrics_max_size": 42.0,
"analysis": {
"analyzer": {},
"char_filter": {},
"filter": {},
"normalizer": {},
"tokenizer": {}
},
"settings": {},
"time_series": {
"": "string"
},
"queries": {
"cache": {
"enabled": true
}
},
"similarity": {},
"mapping": {
"coerce": true,
"total_fields": {
"limit": 42.0,
"ignore_dynamic_beyond_limit": true
},
"depth": {
"limit": 42.0
},
"nested_fields": {
"limit": 42.0
},
"nested_objects": {
"limit": 42.0
},
"field_name_length": {
"limit": 42.0
},
"dimension_fields": {
"limit": 42.0
},
"source": {
"mode": "disabled"
},
"ignore_malformed": true
},
"indexing.slowlog": {
"level": "string",
"source": 42.0,
"reformat": true,
"threshold": {
"index": {
"warn": "string",
"info": "string",
"debug": "string",
"trace": "string"
}
}
},
"indexing_pressure": {
"memory": {
"limit": 42.0
}
},
"store": {
"": "fs",
"allow_mmap": true
}
},
"data_stream": "string",
"lifecycle": {
"data_retention": "string",
"downsampling": {
"rounds": [
{
"after": "string",
"config": {}
}
]
},
"enabled": true
}
}
}
Open a closed index
For data streams, the API opens any closed backing indices.
A closed index is blocked for read/write operations and does not allow all operations that opened indices allow. It is not possible to index documents or to search for documents in a closed index. This allows closed indices to not have to maintain internal data structures for indexing or searching documents, resulting in a smaller overhead on the cluster.
When opening or closing an index, the master is responsible for restarting the index shards to reflect the new state of the index. The shards will then go through the normal recovery process. The data of opened or closed indices is automatically replicated by the cluster to ensure that enough shard copies are safely kept around at all times.
You can open and close multiple indices.
An error is thrown if the request explicitly refers to a missing index.
This behavior can be turned off by using the ignore_unavailable=true
parameter.
By default, you must explicitly name the indices you are opening or closing.
To open or close indices with _all
, *
, or other wildcard expressions, change the action.destructive_requires_name
setting to false
.
This setting can also be changed with the cluster update settings API.
Closed indices consume a significant amount of disk-space which can cause problems in managed environments.
Closing indices can be turned off with the cluster settings API by setting cluster.indices.close.enable
to false
.
Because opening or closing an index allocates its shards, the wait_for_active_shards
setting on index creation applies to the _open
and _close
index actions as well.
Path parameters
-
index
string | array[string] Required Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (
*
). By default, you must explicitly name the indices you using to limit the request. To limit a request using_all
,*
, or other wildcard expressions, change theaction.destructive_requires_name
setting to false. You can update this setting in theelasticsearch.yml
file or using the cluster update settings API.
Query parameters
-
allow_no_indices
boolean If
false
, the request returns an error if any wildcard expression, index alias, or_all
value targets only missing or closed indices. This behavior applies even if the request targets other open indices. -
expand_wildcards
string | array[string] Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as
open,hidden
. Valid values are:all
,open
,closed
,hidden
,none
. -
master_timeout
string Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
-
timeout
string Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
-
wait_for_active_shards
number | string The number of shard copies that must be active before proceeding with the operation. Set to
all
or any positive integer up to the total number of shards in the index (number_of_replicas+1
).
curl \
--request POST 'http://api.example.com/{index}/_open' \
--header "Authorization: $API_KEY"
{
"acknowledged" : true,
"shards_acknowledged" : true
}
Refresh an index
A refresh makes recent operations performed on one or more indices available for search. For data streams, the API runs the refresh operation on the stream’s backing indices.
By default, Elasticsearch periodically refreshes indices every second, but only on indices that have received one search request or more in the last 30 seconds.
You can change this default interval with the index.refresh_interval
setting.
Refresh requests are synchronous and do not return a response until the refresh operation completes.
Refreshes are resource-intensive. To ensure good cluster performance, it's recommended to wait for Elasticsearch's periodic refresh rather than performing an explicit refresh when possible.
If your application workflow indexes documents and then runs a search to retrieve the indexed document, it's recommended to use the index API's refresh=wait_for
query parameter option.
This option ensures the indexing operation waits for a periodic refresh before running the search.
Path parameters
-
index
string | array[string] Required Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (
*
). To target all data streams and indices, omit this parameter or use*
or_all
.
Query parameters
-
allow_no_indices
boolean If
false
, the request returns an error if any wildcard expression, index alias, or_all
value targets only missing or closed indices. This behavior applies even if the request targets other open indices. -
expand_wildcards
string | array[string] Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as
open,hidden
. Valid values are:all
,open
,closed
,hidden
,none
.
curl \
--request POST 'http://api.example.com/{index}/_refresh' \
--header "Authorization: $API_KEY"
{
"_shards": {
"failed": 42.0,
"successful": 42.0,
"total": 42.0,
"failures": [
{
"index": "string",
"node": "string",
"reason": {
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
},
"shard": 42.0,
"status": "string"
}
],
"skipped": 42.0
}
}
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. -
all_shards
boolean If
true
, the validation is executed on all shards instead of one random shard per index. -
analyzer
string Analyzer to use for the query string. This parameter can only be used when the
q
query string parameter is specified. -
analyze_wildcard
boolean If
true
, wildcard and prefix queries are analyzed. -
default_operator
string The default operator for query string query:
AND
orOR
.Values are
and
,AND
,or
, orOR
. -
df
string Field to use as default where no field prefix is given in the query string. This parameter can only be used when the
q
query string parameter is 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, such as
open,hidden
. Valid values are:all
,open
,closed
,hidden
,none
. -
explain
boolean If
true
, the response returns detailed information if an error has occurred. -
lenient
boolean If
true
, format-based query failures (such as providing text to a numeric field) in the query string will be ignored. -
rewrite
boolean If
true
, returns a more detailed explanation showing the actual Lucene query that will be executed. -
q
string Query in the Lucene query string syntax.
Body
-
query
object An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation
curl \
--request GET 'http://api.example.com/_validate/query' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"query":{}}'
{
"query": {}
}
{
"explanations": [
{
"error": "string",
"explanation": "string",
"index": "string",
"valid": true
}
],
"_shards": {
"failed": 42.0,
"successful": 42.0,
"total": 42.0,
"failures": [
{
"index": "string",
"node": "string",
"reason": {
"type": "string",
"reason": "string",
"stack_trace": "string",
"caused_by": {},
"root_cause": [
{}
],
"suppressed": [
{}
]
},
"shard": 42.0,
"status": "string"
}
],
"skipped": 42.0
},
"valid": true,
"error": "string"
}
Create an JinaAI inference endpoint
Added in 8.18.0
Create an inference endpoint to perform an inference task with the jinaai
service.
To review the available rerank
models, refer to https://jina.ai/reranker.
To review the available text_embedding
models, refer to the https://jina.ai/embeddings/.
When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running.
After creating the endpoint, wait for the model deployment to complete before using it.
To verify the deployment status, use the get trained model statistics API.
Look for "state": "fully_allocated"
in the response and ensure that the "allocation_count"
matches the "target_allocation_count"
.
Avoid creating multiple endpoints for the same model unless required, as each endpoint consumes significant resources.
Path parameters
-
task_type
string Required The type of the inference task that the model will perform.
Values are
rerank
ortext_embedding
. -
jinaai_inference_id
string Required The unique identifier of the inference endpoint.
Body
-
chunking_settings
object -
service
string Required Value is
jinaai
. -
service_settings
object Required -
task_settings
object
curl \
--request PUT 'http://api.example.com/_inference/{task_type}/{jinaai_inference_id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"service\": \"jinaai\",\n \"service_settings\": {\n \"model_id\": \"jina-embeddings-v3\",\n \"api_key\": \"JinaAi-Api-key\"\n }\n}"'
{
"service": "jinaai",
"service_settings": {
"model_id": "jina-embeddings-v3",
"api_key": "JinaAi-Api-key"
}
}
{
"service": "jinaai",
"service_settings": {
"api_key": "JinaAI-Api-key",
"model_id": "jina-reranker-v2-base-multilingual"
},
"task_settings": {
"top_n": 10,
"return_documents": true
}
}
{
"chunking_settings": {
"max_chunk_size": 42.0,
"overlap": 42.0,
"sentence_overlap": 42.0,
"strategy": "string"
},
"service": "string",
"service_settings": {},
"task_settings": {},
"inference_id": "string",
"task_type": "sparse_embedding"
}
Licensing
Licensing APIs enable you to manage your licenses.
Get calendar configuration info
Added in 6.2.0
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.
curl \
--request POST 'http://api.example.com/_ml/calendars/{calendar_id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"page":{"from":42.0,"size":42.0}}'
{
"page": {
"from": 42.0,
"size": 42.0
}
}
{
"calendars": [
{
"calendar_id": "string",
"description": "string",
"job_ids": [
"string"
]
}
],
"count": 42.0
}
Add anomaly detection job to calendar
Added in 6.2.0
Path parameters
-
calendar_id
string Required A string that uniquely identifies a calendar.
-
job_id
string | array[string] Required An identifier for the anomaly detection jobs. It can be a job identifier, a group name, or a comma-separated list of jobs or groups.
curl \
--request PUT 'http://api.example.com/_ml/calendars/{calendar_id}/jobs/{job_id}' \
--header "Authorization: $API_KEY"
{
"calendar_id": "string",
"description": "string",
"": "string"
}
Delete anomaly jobs from a calendar
Added in 6.2.0
Path parameters
-
calendar_id
string Required A string that uniquely identifies a calendar.
-
job_id
string | array[string] Required An identifier for the anomaly detection jobs. It can be a job identifier, a group name, or a comma-separated list of jobs or groups.
curl \
--request DELETE 'http://api.example.com/_ml/calendars/{calendar_id}/jobs/{job_id}' \
--header "Authorization: $API_KEY"
{
"calendar_id": "planned-outages",
"job_ids": []
}
Get model snapshots info
Added in 5.4.0
Path parameters
-
job_id
string Required Identifier for the anomaly detection job.
-
snapshot_id
string Required A numerical character string that uniquely identifies the model snapshot. You can get information for multiple snapshots by using a comma-separated list or a wildcard expression. You can get all snapshots by using
_all
, by specifying*
as the snapshot ID, or by omitting the snapshot ID.
Query parameters
-
desc
boolean If true, the results are sorted in descending order.
-
end
string | number Returns snapshots with timestamps earlier than this time.
-
from
number Skips the specified number of snapshots.
-
size
number Specifies the maximum number of snapshots to obtain.
-
sort
string Specifies the sort field for the requested snapshots. By default, the snapshots are sorted by their timestamp.
-
start
string | number Returns snapshots with timestamps after this time.
Body
-
desc
boolean Refer to the description for the
desc
query parameter. 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.
-
page
object -
sort
string Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
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.
curl \
--request GET 'http://api.example.com/_ml/anomaly_detectors/{job_id}/model_snapshots/{snapshot_id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"desc":true,"":"string","page":{"from":42.0,"size":42.0},"sort":"string"}'
{
"desc": true,
"": "string",
"page": {
"from": 42.0,
"size": 42.0
},
"sort": "string"
}
{
"count": 42.0,
"model_snapshots": [
{
"description": "string",
"job_id": "string",
"latest_record_time_stamp": 42.0,
"latest_result_time_stamp": 42.0,
"min_version": "string",
"model_size_stats": {
"bucket_allocation_failures_count": 42.0,
"job_id": "string",
"": 42.0,
"memory_status": "ok",
"assignment_memory_basis": "string",
"result_type": "string",
"total_by_field_count": 42.0,
"total_over_field_count": 42.0,
"total_partition_field_count": 42.0,
"categorization_status": "ok",
"categorized_doc_count": 42.0,
"dead_category_count": 42.0,
"failed_category_count": 42.0,
"frequent_category_count": 42.0,
"rare_category_count": 42.0,
"total_category_count": 42.0,
"timestamp": 42.0
},
"retain": true,
"snapshot_doc_count": 42.0,
"snapshot_id": "string",
"timestamp": 42.0
}
]
}
Force buffered data to be processed
Added in 5.4.0
The flush jobs API is only applicable when sending data for analysis using the post data API. Depending on the content of the buffer, then it might additionally calculate new results. Both flush and close operations are similar, however the flush is more efficient if you are expecting to send more data for analysis. When flushing, the job remains open and is available to continue analyzing data. A close operation additionally prunes and persists the model state to disk and the job must be opened again before analyzing further data.
Path parameters
-
job_id
string Required Identifier for the anomaly detection job.
Query parameters
-
advance_time
string | number Specifies to advance to a particular time value. Results are generated and the model is updated for data from the specified time interval.
-
calc_interim
boolean If true, calculates the interim results for the most recent bucket or all buckets within the latency period.
-
end
string | number When used in conjunction with
calc_interim
andstart
, specifies the range of buckets on which to calculate interim results. -
skip_time
string | number Specifies to skip to a particular time value. Results are not generated and the model is not updated for data from the specified time interval.
-
start
string | number When used in conjunction with
calc_interim
, specifies the range of buckets on which to calculate interim results.
Body
advance_time
string | number A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
-
calc_interim
boolean Refer to the description for the
calc_interim
query parameter. 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.
skip_time
string | number A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
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.
curl \
--request POST 'http://api.example.com/_ml/anomaly_detectors/{job_id}/_flush' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"":"string","calc_interim":true}'
{
"": "string",
"calc_interim": true
}
{
"flushed": true,
"last_finalized_bucket_end": 42.0
}
Get data frame analytics jobs usage info
Added in 7.3.0
Query parameters
-
allow_no_match
boolean Specifies what to do when the request:
- Contains wildcard expressions and there are no data frame analytics jobs that match.
- Contains the
_all
string or no identifiers and there are no matches. - Contains wildcard expressions and there are only partial matches.
The default value returns an empty data_frame_analytics array when there are no matches and the subset of results when there are partial matches. If this parameter is
false
, the request returns a 404 status code when there are no matches or only partial matches. -
from
number Skips the specified number of data frame analytics jobs.
-
size
number Specifies the maximum number of data frame analytics jobs to obtain.
-
verbose
boolean Defines whether the stats response should be verbose.
curl \
--request GET 'http://api.example.com/_ml/data_frame/analytics/_stats' \
--header "Authorization: $API_KEY"
{
"count": 42.0,
"data_frame_analytics": [
{
"analysis_stats": {
"classification_stats": {
"hyperparameters": {
"alpha": 42.0,
"lambda": 42.0,
"gamma": 42.0,
"eta": 42.0,
"eta_growth_rate_per_tree": 42.0,
"feature_bag_fraction": 42.0,
"downsample_factor": 42.0,
"max_attempts_to_add_tree": 42.0,
"max_optimization_rounds_per_hyperparameter": 42.0,
"max_trees": 42.0,
"num_folds": 42.0,
"num_splits_per_feature": 42.0,
"soft_tree_depth_limit": 42.0,
"soft_tree_depth_tolerance": 42.0
},
"iteration": 42.0,
"": 42.0,
"timing_stats": {},
"validation_loss": {
"fold_values": [
"string"
],
"loss_type": "string"
}
},
"outlier_detection_stats": {
"parameters": {
"compute_feature_influence": true,
"feature_influence_threshold": 42.0,
"method": "string",
"n_neighbors": 42.0,
"outlier_fraction": 42.0,
"standardization_enabled": true
},
"": 42.0,
"timing_stats": {}
},
"regression_stats": {
"hyperparameters": {
"alpha": 42.0,
"lambda": 42.0,
"gamma": 42.0,
"eta": 42.0,
"eta_growth_rate_per_tree": 42.0,
"feature_bag_fraction": 42.0,
"downsample_factor": 42.0,
"max_attempts_to_add_tree": 42.0,
"max_optimization_rounds_per_hyperparameter": 42.0,
"max_trees": 42.0,
"num_folds": 42.0,
"num_splits_per_feature": 42.0,
"soft_tree_depth_limit": 42.0,
"soft_tree_depth_tolerance": 42.0
},
"iteration": 42.0,
"": 42.0,
"timing_stats": {},
"validation_loss": {
"fold_values": [
"string"
],
"loss_type": "string"
}
}
},
"assignment_explanation": "string",
"data_counts": {
"skipped_docs_count": 42.0,
"test_docs_count": 42.0,
"training_docs_count": 42.0
},
"id": "string",
"memory_usage": {
"memory_reestimate_bytes": 42.0,
"peak_usage_bytes": 42.0,
"status": "string",
"": 42.0
},
"node": {
"attributes": {
"additionalProperty1": "string",
"additionalProperty2": "string"
},
"ephemeral_id": "string",
"id": "string",
"name": "string",
"transport_address": "string"
},
"progress": [
{
"phase": "string",
"progress_percent": 42.0
}
],
"state": "started"
}
]
}
Reindex legacy backing indices
Technical preview
Reindex all legacy backing indices for a data stream. This operation occurs in a persistent task. The persistent task ID is returned immediately and the reindexing work is completed in that task.
curl \
--request POST 'http://api.example.com/_migration/reindex' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"mode":"upgrade","source":{"index":"string"}}'
{
"mode": "upgrade",
"source": {
"index": "string"
}
}
{
"acknowledged": true
}
Get the shutdown status
Added in 7.13.0
Get information about nodes that are ready to be shut down, have shut down preparations still in progress, or have stalled. The API returns status information for each part of the shut down process.
NOTE: This feature is designed for indirect use by Elasticsearch Service, Elastic Cloud Enterprise, and Elastic Cloud on Kubernetes. Direct use is not supported.
If the operator privileges feature is enabled, you must be an operator to use this API.
Path parameters
-
node_id
string | array[string] Required Which node for which to retrieve the shutdown status
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
nanos
,micros
,ms
,s
,m
,h
, ord
.
curl \
--request GET 'http://api.example.com/_nodes/{node_id}/shutdown' \
--header "Authorization: $API_KEY"
{
"nodes": [
{
"node_id": "USpTGYaBSIKbgSUJR2Z9lg",
"type": "RESTART",
"reason": "Demonstrating how the node shutdown API works",
"shutdown_startedmillis": 1624406108685,
"allocation_delay": "10m",
"status": "COMPLETE",
"shard_migration": {
"status": "COMPLETE",
"shard_migrations_remaining": 0,
"explanation": "no shard relocation is necessary for a node restart"
},
"persistent_tasks": {
"status": "COMPLETE"
},
"plugins": {
"status": "COMPLETE"
}
}
]
}
Get a query ruleset
Added in 8.10.0
Get details about a query ruleset.
Path parameters
-
ruleset_id
string Required The unique identifier of the query ruleset
curl \
--request GET 'http://api.example.com/_query_rules/{ruleset_id}' \
--header "Authorization: $API_KEY"
{
"ruleset_id": "my-ruleset",
"rules": [
{
"rule_id": "my-rule1",
"type": "pinned",
"criteria": [
{
"type": "contains",
"metadata": "query_string",
"values": [ "pugs", "puggles" ]
}
],
"actions": {
"ids": [
"id1",
"id2"
]
}
},
{
"rule_id": "my-rule2",
"type": "pinned",
"criteria": [
{
"type": "fuzzy",
"metadata": "query_string",
"values": [ "rescue dogs" ]
}
],
"actions": {
"docs": [
{
"_index": "index1",
"_id": "id3"
},
{
"_index": "index2",
"_id": "id4"
}
]
}
}
]
}
Open a point in time
Added in 7.10.0
A search request by default runs against the most recent visible data of the target indices,
which is called point in time. Elasticsearch pit (point in time) is a lightweight view into the
state of the data as it existed when initiated. In some cases, it’s preferred to perform multiple
search requests using the same point in time. For example, if refreshes happen between
search_after
requests, then the results of those requests might not be consistent as changes happening
between searches are only visible to the more recent point in time.
A point in time must be opened explicitly before being used in search requests.
A subsequent search request with the pit
parameter must not specify index
, routing
, or preference
values as these parameters are copied from the point in time.
Just like regular searches, you can use from
and size
to page through point in time search results, up to the first 10,000 hits.
If you want to retrieve more hits, use PIT with search_after
.
IMPORTANT: The open point in time request and each subsequent search request can return different identifiers; always use the most recently received ID for the next search request.
When a PIT that contains shard failures is used in a search request, the missing are always reported in the search response as a NoShardAvailableActionException
exception.
To get rid of these exceptions, a new PIT needs to be created so that shards missing from the previous PIT can be handled, assuming they become available in the meantime.
Keeping point in time alive
The keep_alive
parameter, which is passed to a open point in time request and search request, extends the time to live of the corresponding point in time.
The value does not need to be long enough to process all data — it just needs to be long enough for the next request.
Normally, the background merge process optimizes the index by merging together smaller segments to create new, bigger segments. Once the smaller segments are no longer needed they are deleted. However, open point-in-times prevent the old segments from being deleted since they are still in use.
TIP: Keeping older segments alive means that more disk space and file handles are needed. Ensure that you have configured your nodes to have ample free file handles.
Additionally, if a segment contains deleted or updated documents then the point in time must keep track of whether each document in the segment was live at the time of the initial search request. Ensure that your nodes have sufficient heap space if you have many open point-in-times on an index that is subject to ongoing deletes or updates. Note that a point-in-time doesn't prevent its associated indices from being deleted. You can check how many point-in-times (that is, search contexts) are open with the nodes stats API.
Path parameters
-
index
string | array[string] Required A comma-separated list of index names to open point in time; use
_all
or empty string to perform the operation on all indices
Query parameters
-
keep_alive
string Required Extend the length of time that the point in time persists.
-
preference
string The node or shard the operation should be performed on. By default, it is random.
-
routing
string A custom value that is used to route operations to a specific shard.
-
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
. Valid values are:all
,open
,closed
,hidden
,none
. -
allow_partial_search_results
boolean Indicates whether the point in time tolerates unavailable shards or shard failures when initially creating the PIT. If
false
, creating a point in time request when a shard is missing or unavailable will throw an exception. Iftrue
, the point in time will contain all the shards that are available at the time of the request. -
Maximum number of concurrent shard requests that each sub-search request executes per node.
Body
-
index_filter
object An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
External documentation
curl \
--request POST 'http://api.example.com/{index}/_pit?keep_alive=string' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"index_filter":{}}'
{
"index_filter": {}
}
{
"id": "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA=",
"_shards": {
"total": 10,
"successful": 10,
"skipped": 0,
"failed": 0
}
}
Create an API key
Added in 6.7.0
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.
Query parameters
-
refresh
string If
true
(the default) then refresh the affected shards to make this operation visible to search, ifwait_for
then wait for a refresh to make this operation visible to search, iffalse
then do nothing with refreshes.Values are
true
,false
, orwait_for
.
Body
Required
-
expiration
string A duration. Units can be
nanos
,micros
,ms
(milliseconds),s
(seconds),m
(minutes),h
(hours) andd
(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 -
metadata
object
curl \
--request POST 'http://api.example.com/_security/api_key' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"name\": \"my-api-key\",\n \"expiration\": \"1d\", \n \"role_descriptors\": { \n \"role-a\": {\n \"cluster\": [\"all\"],\n \"indices\": [\n {\n \"names\": [\"index-a*\"],\n \"privileges\": [\"read\"]\n }\n ]\n },\n \"role-b\": {\n \"cluster\": [\"all\"],\n \"indices\": [\n {\n \"names\": [\"index-b*\"],\n \"privileges\": [\"all\"]\n }\n ]\n }\n },\n \"metadata\": {\n \"application\": \"my-application\",\n \"environment\": {\n \"level\": 1,\n \"trusted\": true,\n \"tags\": [\"dev\", \"staging\"]\n }\n }\n}"'
{
"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"]
}
}
}
{
"id": "VuaCfGcBCdbkQm-e5aOx",
"name": "my-api-key",
"expiration": 1544068612110,
"api_key": "ui2lp2axTNmsyakw9tvNnw",
"encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
}
Delegate PKI authentication
Added in 7.4.0
This API implements the exchange of an X509Certificate chain for an Elasticsearch access token.
The certificate chain is validated, according to RFC 5280, by sequentially considering the trust configuration of every installed PKI realm that has delegation.enabled
set to true
.
A successfully trusted client certificate is also subject to the validation of the subject distinguished name according to thw username_pattern
of the respective realm.
This API is called by smart and trusted proxies, such as Kibana, which terminate the user's TLS session but still want to authenticate the user by using a PKI realm—-as if the user connected directly to Elasticsearch.
IMPORTANT: The association between the subject public key in the target certificate and the corresponding private key is not validated. This is part of the TLS authentication process and it is delegated to the proxy that calls this API. The proxy is trusted to have performed the TLS authentication and this API translates that authentication into an Elasticsearch access token.
Body
Required
-
x509_certificate_chain
array[string] Required The X509Certificate chain, which is represented as an ordered string array. Each string in the array is a base64-encoded (Section 4 of RFC4648 - not base64url-encoded) of the certificate's DER encoding.
The first element is the target certificate that contains the subject distinguished name that is requesting access. This may be followed by additional certificates; each subsequent certificate is used to certify the previous one.
curl \
--request POST 'http://api.example.com/_security/delegate_pki' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n\"x509_certificate_chain\": [\"MIIDeDCCAmCgAwIBAgIUBzj/nGGKxP2iXawsSquHmQjCJmMwDQYJKoZIhvcNAQELBQAwUzErMCkGA1UEAxMiRWxhc3RpY3NlYXJjaCBUZXN0IEludGVybWVkaWF0ZSBDQTEWMBQGA1UECxMNRWxhc3RpY3NlYXJjaDEMMAoGA1UEChMDb3JnMB4XDTIzMDcxODE5MjkwNloXDTQzMDcxMzE5MjkwNlowSjEiMCAGA1UEAxMZRWxhc3RpY3NlYXJjaCBUZXN0IENsaWVudDEWMBQGA1UECxMNRWxhc3RpY3NlYXJjaDEMMAoGA1UEChMDb3JnMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAllHL4pQkkfwAm/oLkxYYO+r950DEy1bjH+4viCHzNADLCTWO+lOZJVlNx7QEzJE3QGMdif9CCBBxQFMapA7oUFCLq84fPSQQu5AnvvbltVD9nwVtCs+9ZGDjMKsz98RhSLMFIkxdxi6HkQ3Lfa4ZSI4lvba4oo+T/GveazBDS+NgmKyq00EOXt3tWi1G9vEVItommzXWfv0agJWzVnLMldwkPqsw0W7zrpyT7FZS4iLbQADGceOW8fiauOGMkscu9zAnDR/SbWl/chYioQOdw6ndFLn1YIFPd37xL0WsdsldTpn0vH3YfzgLMffT/3P6YlwBegWzsx6FnM/93Ecb4wIDAQABo00wSzAJBgNVHRMEAjAAMB0GA1UdDgQWBBQKNRwjW+Ad/FN1Rpoqme/5+jrFWzAfBgNVHSMEGDAWgBRcya0c0x/PaI7MbmJVIylWgLqXNjANBgkqhkiG9w0BAQsFAAOCAQEACZ3PF7Uqu47lplXHP6YlzYL2jL0D28hpj5lGtdha4Muw1m/BjDb0Pu8l0NQ1z3AP6AVcvjNDkQq6Y5jeSz0bwQlealQpYfo7EMXjOidrft1GbqOMFmTBLpLA9SvwYGobSTXWTkJzonqVaTcf80HpMgM2uEhodwTcvz6v1WEfeT/HMjmdIsq4ImrOL9RNrcZG6nWfw0HR3JNOgrbfyEztEI471jHznZ336OEcyX7gQuvHE8tOv5+oD1d7s3Xg1yuFp+Ynh+FfOi3hPCuaHA+7F6fLmzMDLVUBAllugst1C3U+L/paD7tqIa4ka+KNPCbSfwazmJrt4XNiivPR4hwH5g==\"]\n}"'
{
"x509_certificate_chain": ["MIIDeDCCAmCgAwIBAgIUBzj/nGGKxP2iXawsSquHmQjCJmMwDQYJKoZIhvcNAQELBQAwUzErMCkGA1UEAxMiRWxhc3RpY3NlYXJjaCBUZXN0IEludGVybWVkaWF0ZSBDQTEWMBQGA1UECxMNRWxhc3RpY3NlYXJjaDEMMAoGA1UEChMDb3JnMB4XDTIzMDcxODE5MjkwNloXDTQzMDcxMzE5MjkwNlowSjEiMCAGA1UEAxMZRWxhc3RpY3NlYXJjaCBUZXN0IENsaWVudDEWMBQGA1UECxMNRWxhc3RpY3NlYXJjaDEMMAoGA1UEChMDb3JnMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAllHL4pQkkfwAm/oLkxYYO+r950DEy1bjH+4viCHzNADLCTWO+lOZJVlNx7QEzJE3QGMdif9CCBBxQFMapA7oUFCLq84fPSQQu5AnvvbltVD9nwVtCs+9ZGDjMKsz98RhSLMFIkxdxi6HkQ3Lfa4ZSI4lvba4oo+T/GveazBDS+NgmKyq00EOXt3tWi1G9vEVItommzXWfv0agJWzVnLMldwkPqsw0W7zrpyT7FZS4iLbQADGceOW8fiauOGMkscu9zAnDR/SbWl/chYioQOdw6ndFLn1YIFPd37xL0WsdsldTpn0vH3YfzgLMffT/3P6YlwBegWzsx6FnM/93Ecb4wIDAQABo00wSzAJBgNVHRMEAjAAMB0GA1UdDgQWBBQKNRwjW+Ad/FN1Rpoqme/5+jrFWzAfBgNVHSMEGDAWgBRcya0c0x/PaI7MbmJVIylWgLqXNjANBgkqhkiG9w0BAQsFAAOCAQEACZ3PF7Uqu47lplXHP6YlzYL2jL0D28hpj5lGtdha4Muw1m/BjDb0Pu8l0NQ1z3AP6AVcvjNDkQq6Y5jeSz0bwQlealQpYfo7EMXjOidrft1GbqOMFmTBLpLA9SvwYGobSTXWTkJzonqVaTcf80HpMgM2uEhodwTcvz6v1WEfeT/HMjmdIsq4ImrOL9RNrcZG6nWfw0HR3JNOgrbfyEztEI471jHznZ336OEcyX7gQuvHE8tOv5+oD1d7s3Xg1yuFp+Ynh+FfOi3hPCuaHA+7F6fLmzMDLVUBAllugst1C3U+L/paD7tqIa4ka+KNPCbSfwazmJrt4XNiivPR4hwH5g=="]
}
{
"access_token": "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
"type": "Bearer",
"expires_in": 1200,
"authentication": {
"username": "Elasticsearch Test Client",
"roles": [],
"full_name": null,
"email": null,
"metadata": {
"pki_dn": "O=org, OU=Elasticsearch, CN=Elasticsearch Test Client",
"pki_delegated_by_user": "test_admin",
"pki_delegated_by_realm": "file"
},
"enabled": true,
"authentication_realm": {
"name": "pki1",
"type": "pki"
},
"lookup_realm": {
"name": "pki1",
"type": "pki"
},
"authentication_type": "realm"
}
}
Get role mappings
Added in 5.5.0
Role mappings define which roles are assigned to each user. The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files. The get role mappings API cannot retrieve role mappings that are defined in role mapping files.
Path parameters
-
name
string | array[string] Required The distinct name that identifies the role mapping. The name is used solely as an identifier to facilitate interaction via the API; it does not affect the behavior of the mapping in any way. You can specify multiple mapping names as a comma-separated list. If you do not specify this parameter, the API returns information about all role mappings.
curl \
--request GET 'http://api.example.com/_security/role_mapping/{name}' \
--header "Authorization: $API_KEY"
{
"mapping1": {
"enabled": true,
"roles": [
"user"
],
"rules": {
"field": {
"username": "*"
}
},
"metadata": {}
}
}
Check user profile privileges
Added in 8.3.0
Determine whether the users associated with the specified user profile IDs have all the requested privileges.
NOTE: The user profile feature is designed only for use by Kibana and Elastic's Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice.
Body
Required
-
uids
array[string] Required A list of profile IDs. The privileges are checked for associated users of the profiles.
-
privileges
object Required
curl \
--request GET 'http://api.example.com/_security/profile/_has_privileges' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"uids\": [\n \"u_LQPnxDxEjIH0GOUoFkZr5Y57YUwSkL9Joiq-g4OCbPc_0\",\n \"u_rzRnxDgEHIH0GOUoFkZr5Y27YUwSk19Joiq=g4OCxxB_1\",\n \"u_does-not-exist_0\"\n ],\n \"privileges\": {\n \"cluster\": [ \"monitor\", \"create_snapshot\", \"manage_ml\" ],\n \"index\" : [\n {\n \"names\": [ \"suppliers\", \"products\" ],\n \"privileges\": [ \"create_doc\"]\n },\n {\n \"names\": [ \"inventory\" ],\n \"privileges\" : [ \"read\", \"write\" ]\n }\n ],\n \"application\": [\n {\n \"application\": \"inventory_manager\",\n \"privileges\" : [ \"read\", \"data:write/inventory\" ],\n \"resources\" : [ \"product/1852563\" ]\n }\n ]\n }\n}"'
{
"uids": [
"u_LQPnxDxEjIH0GOUoFkZr5Y57YUwSkL9Joiq-g4OCbPc_0",
"u_rzRnxDgEHIH0GOUoFkZr5Y27YUwSk19Joiq=g4OCxxB_1",
"u_does-not-exist_0"
],
"privileges": {
"cluster": [ "monitor", "create_snapshot", "manage_ml" ],
"index" : [
{
"names": [ "suppliers", "products" ],
"privileges": [ "create_doc"]
},
{
"names": [ "inventory" ],
"privileges" : [ "read", "write" ]
}
],
"application": [
{
"application": "inventory_manager",
"privileges" : [ "read", "data:write/inventory" ],
"resources" : [ "product/1852563" ]
}
]
}
}
{
"has_privilege_uids": ["u_rzRnxDgEHIH0GOUoFkZr5Y27YUwSk19Joiq=g4OCxxB_1"],
"errors": {
"count": 1,
"details": {
"u_does-not-exist_0": {
"type": "resource_not_found_exception",
"reason": "profile document not found"
}
}
}
}
Create a snapshot
Added in 0.0.0
Take a snapshot of a cluster or of data streams and indices.
Path parameters
-
repository
string Required Repository for the snapshot.
-
snapshot
string Required Name of the snapshot. Must be unique in the repository.
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.
-
wait_for_completion
boolean If
true
, the request returns a response when the snapshot is complete. Iffalse
, the request returns a response when the snapshot initializes.
Body
-
include_global_state
boolean If
true
, the current cluster state is included in the snapshot. The cluster state includes persistent cluster settings, composable index templates, legacy index templates, ingest pipelines, and ILM policies. It also includes data stored in system indices, such as Watches and task records (configurable viafeature_states
). -
indices
string | array[string] -
feature_states
array[string] Feature states to include in the snapshot. Each feature state includes one or more system indices containing related data. You can view a list of eligible features using the get features API. If
include_global_state
istrue
, all current feature states are included by default. Ifinclude_global_state
isfalse
, no feature states are included by default. -
metadata
object -
partial
boolean If
true
, allows restoring a partial snapshot of indices with unavailable shards. Only shards that were successfully included in the snapshot will be restored. All missing shards will be recreated as empty. Iffalse
, the entire restore operation will fail if one or more indices included in the snapshot do not have all primary shards available.
curl \
--request PUT 'http://api.example.com/_snapshot/{repository}/{snapshot}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"indices\": \"index_1,index_2\",\n \"ignore_unavailable\": true,\n \"include_global_state\": false,\n \"metadata\": {\n \"taken_by\": \"user123\",\n \"taken_because\": \"backup before upgrading\"\n }\n}"'
{
"indices": "index_1,index_2",
"ignore_unavailable": true,
"include_global_state": false,
"metadata": {
"taken_by": "user123",
"taken_because": "backup before upgrading"
}
}
{
"snapshot": {
"snapshot": "snapshot_2",
"uuid": "vdRctLCxSketdKb54xw67g",
"repository": "my_repository",
"version_id": <version_id>,
"version": <version>,
"indices": [],
"data_streams": [],
"feature_states": [],
"include_global_state": false,
"metadata": {
"taken_by": "user123",
"taken_because": "backup before upgrading"
},
"state": "SUCCESS",
"start_time": "2020-06-25T14:00:28.850Z",
"start_time_in_millis": 1593093628850,
"end_time": "2020-06-25T14:00:28.850Z",
"end_time_in_millis": 1593094752018,
"duration_in_millis": 0,
"failures": [],
"shards": {
"total": 0,
"failed": 0,
"successful": 0
}
}
}
Synonyms
The synonyms management API provides a convenient way to define and manage synonyms in an internal system index. Related synonyms can be grouped in a "synonyms set". Create as many synonym sets as you need.