Get field data cache information

GET /_cat/fielddata/{fields}

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

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

Path parameters

fields string | array[string] Required

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

Query parameters

bytes string

The unit used to display byte values.

Values are b, kb, mb, gb, tb, or pb.
fields string | array[string]

Comma-separated list of fields used to limit returned information.
h string | array[string]

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

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

Responses

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

GET /_cat/fielddata/{fields}

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

Response examples (200)

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

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

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

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

Get anomaly detection jobs Added in 7.7.0

GET /_cat/ml/anomaly_detectors

Api key auth Basic auth Bearer auth

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

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

Query parameters

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

The unit used to display byte values.

Values are b, kb, mb, gb, tb, or pb.
h string | array[string]

Comma-separated list of column names to display.
s string | array[string]

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

The unit used to display time values.

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

Responses

200 application/json
Hide response attributes Show response attributes object
- id string
- state string
  
  Values are closing, closed, opened, failed, or opening.
- opened_time string
  
  For open jobs only, the amount of time the job has been opened.
- assignment_explanation string
  
  For open anomaly detection jobs only, contains messages relating to the selection of a node to run the job.
- data.processed_records string
  
  The number of input documents that have been processed by the anomaly detection job. This value includes documents with missing fields, since they are nonetheless analyzed. If you use datafeeds and have aggregations in your search query, the processed_record_count is the number of aggregation results processed, not the number of Elasticsearch documents.
- data.processed_fields string
  
  The total number of fields in all the documents that have been processed by the anomaly detection job. Only fields that are specified in the detector configuration object contribute to this count. The timestamp is not included in this count.
- data.input_bytes number | string
  
  One of:
  ByteSize number ByteSize string
- data.input_records string
  
  The number of input documents posted to the anomaly detection job.
- data.input_fields string
  
  The total number of fields in input documents posted to the anomaly detection job. This count includes fields that are not used in the analysis. However, be aware that if you are using a datafeed, it extracts only the required fields from the documents it retrieves before posting them to the job.
- data.invalid_dates string
  
  The number of input documents with either a missing date field or a date that could not be parsed.
- data.missing_fields string
  
  The number of input documents that are missing a field that the anomaly detection job is configured to analyze. Input documents with missing fields are still processed because it is possible that not all fields are missing. If you are using datafeeds or posting data to the job in JSON format, a high missing_field_count is often not an indication of data issues. It is not necessarily a cause for concern.
- data.out_of_order_timestamps string
  
  The number of input documents that have a timestamp chronologically preceding the start of the current anomaly detection bucket offset by the latency window. This information is applicable only when you provide data to the anomaly detection job by using the post data API. These out of order documents are discarded, since jobs require time series data to be in ascending chronological order.
- data.empty_buckets string
  
  The number of buckets which did not contain any data. If your data contains many empty buckets, consider increasing your bucket_span or using functions that are tolerant to gaps in data such as mean, non_null_sum or non_zero_count.
- data.sparse_buckets string
  
  The number of buckets that contained few data points compared to the expected number of data points. If your data contains many sparse buckets, consider using a longer bucket_span.
- data.buckets string
  
  The total number of buckets processed.
- data.earliest_record string
  
  The timestamp of the earliest chronologically input document.
- data.latest_record string
  
  The timestamp of the latest chronologically input document.
- data.last string
  
  The timestamp at which data was last analyzed, according to server time.
- data.last_empty_bucket string
  
  The timestamp of the last bucket that did not contain any data.
- data.last_sparse_bucket string
  
  The timestamp of the last bucket that was considered sparse.
- model.bytes number | string
  
  One of:
  ByteSize number ByteSize string
- model.memory_status string
  
  Values are ok, soft_limit, or hard_limit.
- model.bytes_exceeded number | string
  
  One of:
  ByteSize number ByteSize string
- model.memory_limit string
  
  The upper limit for model memory usage, checked on increasing values.
- model.by_fields string
  
  The number of by field values that were analyzed by the models. This value is cumulative for all detectors in the job.
- model.over_fields string
  
  The number of over field values that were analyzed by the models. This value is cumulative for all detectors in the job.
- model.partition_fields string
  
  The number of partition field values that were analyzed by the models. This value is cumulative for all detectors in the job.
- model.bucket_allocation_failures string
  
  The number of buckets for which new entities in incoming data were not processed due to insufficient model memory. This situation is also signified by a hard_limit: memory_status property value.
- model.categorization_status string
  
  Values are ok or warn.
- model.categorized_doc_count string
  
  The number of documents that have had a field categorized.
- model.total_category_count string
  
  The number of categories created by categorization.
- model.frequent_category_count string
  
  The number of categories that match more than 1% of categorized documents.
- model.rare_category_count string
  
  The number of categories that match just one categorized document.
- model.dead_category_count string
  
  The number of categories created by categorization that will never be assigned again because another category’s definition makes it a superset of the dead category. Dead categories are a side effect of the way categorization has no prior training.
- model.failed_category_count string
  
  The number of times that categorization wanted to create a new category but couldn’t because the job had hit its model_memory_limit. This count does not track which specific categories failed to be created. Therefore you cannot use this value to determine the number of unique categories that were missed.
- model.log_time string
  
  The timestamp when the model stats were gathered, according to server time.
- model.timestamp string
  
  The timestamp of the last record when the model stats were gathered.
- forecasts.total string
  
  The number of individual forecasts currently available for the job. A value of one or more indicates that forecasts exist.
- forecasts.memory.min string
  
  The minimum memory usage in bytes for forecasts related to the anomaly detection job.
- forecasts.memory.max string
  
  The maximum memory usage in bytes for forecasts related to the anomaly detection job.
- forecasts.memory.avg string
  
  The average memory usage in bytes for forecasts related to the anomaly detection job.
- forecasts.memory.total string
  
  The total memory usage in bytes for forecasts related to the anomaly detection job.
- forecasts.records.min string
  
  The minimum number of model_forecast documents written for forecasts related to the anomaly detection job.
- forecasts.records.max string
  
  The maximum number of model_forecast documents written for forecasts related to the anomaly detection job.
- forecasts.records.avg string
  
  The average number of model_forecast documents written for forecasts related to the anomaly detection job.
- forecasts.records.total string
  
  The total number of model_forecast documents written for forecasts related to the anomaly detection job.
- forecasts.time.min string
  
  The minimum runtime in milliseconds for forecasts related to the anomaly detection job.
- forecasts.time.max string
  
  The maximum runtime in milliseconds for forecasts related to the anomaly detection job.
- forecasts.time.avg string
  
  The average runtime in milliseconds for forecasts related to the anomaly detection job.
- forecasts.time.total string
  
  The total runtime in milliseconds for forecasts related to the anomaly detection job.
- node.id string
- node.name string
  
  The name of the assigned node.
- node.ephemeral_id string
- node.address string
  
  The network address of the assigned node.
- buckets.count string
  
  The number of bucket results produced by the job.
- buckets.time.total string
  
  The sum of all bucket processing times, in milliseconds.
- buckets.time.min string
  
  The minimum of all bucket processing times, in milliseconds.
- buckets.time.max string
  
  The maximum of all bucket processing times, in milliseconds.
- buckets.time.exp_avg string
  
  The exponential moving average of all bucket processing times, in milliseconds.
- buckets.time.exp_avg_hour string
  
  The exponential moving average of bucket processing times calculated in a one hour time window, in milliseconds.

GET /_cat/ml/anomaly_detectors

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

Response examples (200)

A successful response from `GET _cat/ml/anomaly_detectors?h=id,s,dpr,mb&v=true&format=json`.

[
  {
    "id": "high_sum_total_sales",
    "s": "closed",
    "dpr": "14022",
    "mb": "1.5mb"
  },
  {
    "id": "low_request_rate",
    "s": "closed",
    "dpr": "1216",
    "mb": "40.5kb"
  },
  {
    "id": "response_code_rates",
    "s": "closed",
    "dpr": "28146",
    "mb": "132.7kb"
  },
  {
    "id": "url_scanning",
    "s": "closed",
    "dpr": "28146",
    "mb": "501.6kb"
  }
]

Get task information Technical preview

GET /_cat/tasks

Api key auth Basic auth Bearer auth

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

Query parameters

actions array[string]

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

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

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

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

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

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

Unit used to display time values.

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

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

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

Responses

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

GET /_cat/tasks

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

Response examples (200)

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

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

Get thread pool statistics

GET /_cat/thread_pool/{thread_pool_patterns}

Api key auth Basic auth Bearer auth

Get thread pool statistics for each node in a cluster. Returned information includes all built-in thread pools and custom thread pools. IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console. They are not intended for use by applications. For application consumption, use the nodes info API.

Path parameters

thread_pool_patterns string | array[string] Required

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

Query parameters

h string | array[string]

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

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

The unit used to display time values.

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

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

Period to wait for a connection to the master node.

Responses

200 application/json
Hide response attributes Show response attributes object
- node_name string
  
  The node name.
- node_id string
- ephemeral_node_id string
  
  The ephemeral node identifier.
- pid string
  
  The process identifier.
- host string
  
  The host name for the current node.
- ip string
  
  The IP address for the current node.
- port string
  
  The bound transport port for the current node.
- name string
  
  The thread pool name.
- type string
  
  The thread pool type. Returned values include fixed, fixed_auto_queue_size, direct, and scaling.
- active string
  
  The number of active threads in the current thread pool.
- pool_size string
  
  The number of threads in the current thread pool.
- queue string
  
  The number of tasks currently in queue.
- queue_size string
  
  The maximum number of tasks permitted in the queue.
- rejected string
  
  The number of rejected tasks.
- largest string
  
  The highest number of active threads in the current thread pool.
- completed string
  
  The number of completed tasks.
- core string | null
  
  The core number of active threads allowed in a scaling thread pool.
  
  One of:
  string-1 string string-2 string | null
- max string | null
  
  The maximum number of active threads allowed in a scaling thread pool.
  
  One of:
  string-1 string string-2 string | null
- size string | null
  
  The number of active threads allowed in a fixed thread pool.
  
  One of:
  string-1 string string-2 string | null
- keep_alive string | null
  
  The thread keep alive time.
  
  One of:
  string-1 string string-2 string | null

GET /_cat/thread_pool/{thread_pool_patterns}

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

Response examples (200)

A successful response from `GET /_cat/thread_pool?format=json`.

[
  {
    "node_name": "node-0",
    "name": "analyze",
    "active": "0",
    "queue": "0",
    "rejected": "0"
  },
  {
    "node_name": "node-0",
    "name": "fetch_shard_started",
    "active": "0",
    "queue": "0",
    "rejected": "0"
  },
  {
    "node_name": "node-0",
    "name": "fetch_shard_store",
    "active": "0",
    "queue": "0",
    "rejected": "0"
  },
  {
    "node_name": "node-0",
    "name": "flush",
    "active": "0",
    "queue": "0",
    "rejected": "0"
  },
  {
    "node_name": "node-0",
    "name": "write",
    "active": "0",
    "queue": "0",
    "rejected": "0"
  }
]

A successful response from `GET /_cat/thread_pool/generic?v=true&h=id,name,active,rejected,completed&format=json`. It returns the `id`, `name`, `active`, `rejected`, and `completed` columns. It also limits returned information to the generic thread pool.

[
  {
    "id": "0EWUhXeBQtaVGlexUeVwMg",
    "name": "generic",
    "active": "0",
    "rejected": "0",
    "completed": "70"
  }
]

Update the connector pipeline Beta

PUT /_connector/{connector_id}/_pipeline

Api key auth Basic auth Bearer auth

When you create a new connector, the configuration of an ingest pipeline is populated with default settings.

Path parameters

connector_id string Required

The unique identifier of the connector to be updated

application/json

Body Required

pipeline object Required
Hide pipeline attributes Show pipeline attributes object
- extract_binary_content boolean Required
- name string Required
- reduce_whitespace boolean Required
- run_ml_inference boolean Required

Responses

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

PUT /_connector/{connector_id}/_pipeline

curl \
 --request PUT 'http://api.example.com/_connector/{connector_id}/_pipeline' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n    \"pipeline\": {\n        \"extract_binary_content\": true,\n        \"name\": \"my-connector-pipeline\",\n        \"reduce_whitespace\": true,\n        \"run_ml_inference\": true\n    }\n}"'

Request example

{
    "pipeline": {
        "extract_binary_content": true,
        "name": "my-connector-pipeline",
        "reduce_whitespace": true,
        "run_ml_inference": true
    }
}

Response examples (200)

{
  "result": "updated"
}

Create a data stream Added in 7.9.0

PUT /_data_stream/{name}

Api key auth Basic auth Bearer auth

You must have a matching index template with data stream enabled.

Path parameters

name string Required

Name of the data stream, which must meet the following criteria: Lowercase only; Cannot include \, /, *, ?, ", <, >, |, ,, #, :, or a space character; Cannot start with -, _, +, or .ds-; Cannot be . or ..; Cannot be longer than 255 bytes. Multi-byte characters count towards this limit faster.

Query parameters

master_timeout string

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

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

Responses

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

PUT /_data_stream/{name}

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

Response examples (200)

{
  "acknowledged": true
}

Get data stream lifecycle stats Added in 8.12.0

GET /_lifecycle/stats

Api key auth Basic auth Bearer auth

Get statistics about the data streams that are managed by a data stream lifecycle.

Responses

200 application/json
Hide response attributes Show response attributes object
- data_stream_count number Required
  
  The count of data streams currently being managed by the data stream lifecycle.
- data_streams array[object] Required
  
  Information about the data streams that are managed by the data stream lifecycle.
  
  Hide data_streams attributes Show data_streams attributes object
  
  backing_indices_in_error number Required
  
  The count of the backing indices for the data stream.
  
  backing_indices_in_total number Required
  
  The count of the backing indices for the data stream that have encountered an error.
  
  name string Required
- last_run_duration_in_millis number
  
  Time unit for milliseconds
- time_between_starts_in_millis number
  
  Time unit for milliseconds

GET /_lifecycle/stats

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

Response examples (200)

A successful response for `GET _lifecycle/stats?human&pretty`

{
  "last_run_duration_in_millis": 2,
  "last_run_duration": "2ms",
  "time_between_starts_in_millis": 9998,
  "time_between_starts": "9.99s",
  "data_streams_count": 2,
  "data_streams": [
    {
      "name": "my-data-stream",
      "backing_indices_in_total": 2,
      "backing_indices_in_error": 0
    },
    {
      "name": "my-other-stream",
      "backing_indices_in_total": 2,
      "backing_indices_in_error": 1
    }
  ]
}

Delete a document

DELETE /{index}/_doc/{id}

Api key auth Basic auth Bearer auth

Remove a JSON document from the specified index.

NOTE: You cannot send deletion requests directly to a data stream. To delete a document in a data stream, you must target the backing index containing the document.

Optimistic concurrency control

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

Versioning

Each document indexed is versioned. When deleting a document, the version can be specified to make sure the relevant document you are trying to delete is actually being deleted and it has not changed in the meantime. Every write operation run on a document, deletes included, causes its version to be incremented. The version number of a deleted document remains available for a short time after deletion to allow for control of concurrent operations. The length of time for which a deleted document's version remains available is determined by the index.gc_deletes index setting.

Routing

If routing is used during indexing, the routing value also needs to be specified to delete a document.

If the _routing mapping is set to required and no routing value is specified, the delete API throws a RoutingMissingException and rejects the request.

For example:

DELETE /my-index-000001/_doc/1?routing=shard-1

This request deletes the document with ID 1, but it is routed based on the user. The document is not deleted if the correct routing is not specified.

Distributed

The delete operation gets hashed into a specific shard ID. It then gets redirected into the primary shard within that ID group and replicated (if needed) to shard replicas within that ID group.

Path parameters

index string Required

The name of the target index.
id string Required

A unique identifier for the document.

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

If true, Elasticsearch refreshes the affected shards to make this operation visible to search. If wait_for, it waits for a refresh to make this operation visible to search. If false, it does nothing with refreshes.

Values are true, false, or wait_for.
routing string

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

The period to wait for active shards.

This parameter is useful for situations where the primary shard assigned to perform the delete operation might not be available when the delete operation runs. Some reasons for this might be that the primary shard is currently recovering from a store or undergoing relocation. By default, the delete operation will wait on the primary shard to become available for up to 1 minute before failing and responding with an error.
version number

An explicit 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, or force.
wait_for_active_shards number | string

The minimum 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 of 1 means it waits for each primary shard to be active.

Responses

200 application/json
Hide response attributes Show response attributes object
- _id string Required
- _index string Required
- _primary_term number
  
  The primary term assigned to the document for the indexing operation.
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.
- _seq_no number
- _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number
- _version number Required
- forced_refresh boolean

DELETE /{index}/_doc/{id}

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

Response examples (200)

A successful response from `DELETE /my-index-000001/_doc/1`, which deletes the JSON document 1 from the `my-index-000001` index.

{
  "_shards": {
    "total": 2,
    "failed": 0,
    "successful": 2
  },
  "_index": "my-index-000001",
  "_id": "1",
  "_version": 2,
  "_primary_term": 1,
  "_seq_no": 5,
  "result": "deleted"
}

Get multiple term vectors

GET /_mtermvectors

Api key auth Basic auth Bearer auth

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.

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 or fielddata_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, or force.

application/json

Body

docs array[object]

An array of existing or artificial documents.
Hide docs attributes Show docs attributes object
- _id string
- _index string
- doc object
  
  An artificial document (a document not present in the index) for which you want to retrieve term vectors.
- fields string | array[string]
- field_statistics boolean
  
  If true, the response includes the document count, sum of document frequencies, and sum of total term frequencies.
- filter object
  Hide filter attributes Show filter attributes object
  
  max_doc_freq number
  
  Ignore words which occur in more than this many docs. Defaults to unbounded.
  
  max_num_terms number
  
  The maximum number of terms that must be returned per field.
  
  max_term_freq number
  
  Ignore words with more than this frequency in the source doc. It defaults to unbounded.
  
  max_word_length number
  
  The maximum word length above which words will be ignored. Defaults to unbounded.
  
  min_doc_freq number
  
  Ignore terms which do not occur in at least this many docs.
  
  min_term_freq number
  
  Ignore words with less than this frequency in the source doc.
  
  min_word_length number
  
  The minimum word length below which words will be ignored.
- 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.
- routing string
- term_statistics boolean
  
  If true, the response includes term frequency and document frequency.
- version number
- version_type string
  
  Values are internal, external, external_gte, or force.
ids array[string]

A simplified syntax to specify documents by their ID if they're in the same index.

Responses

200 application/json
Hide response attribute Show response attribute object
- docs array[object] Required
  
  Hide docs attributes Show docs attributes object
  
  _id string
  
  _index string Required
  
  _version number
  
  took number
  
  found boolean
  
  term_vectors object
  
  Hide term_vectors attribute Show term_vectors attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  field_statistics object
  
  Hide field_statistics attributes Show field_statistics attributes object
  
  doc_count number Required
  
  sum_doc_freq number Required
  
  sum_ttf number Required
  
  terms object Required
  
  Hide terms attribute Show terms attribute object
  
  * object Additional properties
  
  error object
  
  Hide error attributes Show error attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]

GET /_mtermvectors

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

Request examples

Run `POST /my-index-000001/_mtermvectors`. When you specify an index in the request URI, the index does not need to be specified for each documents in the request body.

{
  "docs": [
      {
        "_id": "2",
        "fields": [
            "message"
        ],
        "term_statistics": true
      },
      {
        "_id": "1"
      }
  ]
}

Run `POST /my-index-000001/_mtermvectors`. If all requested documents are in same index and the parameters are the same, you can use a simplified syntax.

{
  "ids": [ "1", "2" ],
  "fields": [
    "message"
  ],
  "term_statistics": true
}

Run `POST /_mtermvectors` to generate term vectors for artificial documents provided in the body of the request. The mapping used is determined by the specified `_index`.

{
  "docs": [
      {
        "_index": "my-index-000001",
        "doc" : {
            "message" : "test test test"
        }
      },
      {
        "_index": "my-index-000001",
        "doc" : {
          "message" : "Another test ..."
        }
      }
  ]
}

Response examples (200)

{
  "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": [
          {}
        ]
      }
    }
  ]
}

Update a document

POST /{index}/_update/{id}

Api key auth Basic auth Bearer auth

Update a document by running a script or passing a partial document.

If the Elasticsearch security features are enabled, you must have the index or write index privilege for the target index or index alias.

The script can update, delete, or skip modifying the document. The API also supports passing a partial document, which is merged into the existing document. To fully replace an existing document, use the index API. This operation:

Gets the document (collocated with the shard) from the index.
Runs the specified script.
Indexes the result.

The document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation.

The _source field must be enabled to use this API. In addition to _source, you can access the following variables through the ctx map: _index, _type, _id, _version, _routing, and _now (the current timestamp).

Path parameters

index string Required

The name of the target index. By default, the index is created automatically if it doesn't exist.
id string Required

A unique identifier for the document to be updated.

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

The script language.
refresh string

If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search. If 'wait_for', it waits for a refresh to make this operation visible to search. If 'false', it does nothing with refreshes.

Values are true, false, or wait_for.
require_alias boolean

If true, the destination must be an index alias.
retry_on_conflict number

The number of times the operation should be retried when a conflict occurs.
routing string

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

The period to wait for the following operations: dynamic mapping updates and waiting for active shards. Elasticsearch waits for at least the timeout period before failing. The actual wait time could be longer, particularly when multiple waits occur.
wait_for_active_shards number | string

The number of copies of each shard that must be active before proceeding with the operation. Set to 'all' or any positive integer up to the total number of shards in the index (number_of_replicas+1). The default value of 1 means it waits for each primary shard to be active.
_source boolean | string | array[string]

If false, source retrieval is turned off. You can also specify a comma-separated list of the fields you want to retrieve.
_source_excludes string | array[string]

The source fields you want to exclude.
_source_includes string | array[string]

The source fields you want to retrieve.

application/json

Body Required

detect_noop boolean

If true, the result in the response is set to noop (no operation) when there are no changes to the document.
doc object

A partial update to an existing document. If both doc and script are specified, doc is ignored.
doc_as_upsert boolean

If true, use the contents of 'doc' as the value of 'upsert'. NOTE: Using ingest pipelines with doc_as_upsert is not supported.
script object
Hide script attributes Show script attributes object
- source string | object
  
  One of:
  ScriptSource string ScriptSource object
- id string
- params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  Hide params attribute Show params attribute object
  
  * object Additional properties
- lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
- options object
  Hide options attribute Show options attribute object
  
  * string Additional properties
scripted_upsert boolean

If true, run the script whether or not the document exists.
_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
One of:
SourceConfig boolean SourceFilter object
Hide attributes Show attributes

excludes string | array[string]

includes string | array[string]
upsert object

If the document does not already exist, the contents of 'upsert' are inserted as a new document. If the document exists, the 'script' is run.

Responses

200 application/json
Hide response attributes Show response attributes object
- _id string Required
- _index string Required
- _primary_term number
  
  The primary term assigned to the document for the indexing operation.
- result string Required
  
  Values are created, updated, deleted, not_found, or noop.
- _seq_no number
- _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number
- _version number Required
- forced_refresh boolean
- get object
  
  Hide get attributes Show get attributes object
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  found boolean Required
  
  _seq_no number
  
  _primary_term number
  
  _routing string
  
  _source object

POST /{index}/_update/{id}

curl \
 --request POST 'http://api.example.com/{index}/_update/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"script\" : {\n    \"source\": \"ctx._source.counter += params.count\",\n    \"lang\": \"painless\",\n    \"params\" : {\n      \"count\" : 4\n    }\n  }\n}"'

Request examples

Run `POST test/_update/1` to increment a counter by using a script.

{
  "script" : {
    "source": "ctx._source.counter += params.count",
    "lang": "painless",
    "params" : {
      "count" : 4
    }
  }
}

Run `POST test/_update/1` to perform a scripted upsert. When `scripted_upsert` is `true`, the script runs whether or not the document exists.

{
  "scripted_upsert": true,
  "script": {
    "source": """
      if ( ctx.op == 'create' ) {
        ctx._source.counter = params.count
      } else {
        ctx._source.counter += params.count
      }
    """,
    "params": {
      "count": 4
    }
  },
  "upsert": {}
}

Run `POST test/_update/1` to perform a doc as upsert. Instead of sending a partial `doc` plus an `upsert` doc, you can set `doc_as_upsert` to `true` to use the contents of `doc` as the `upsert` value.

{
  "doc": {
    "name": "new_name"
  },
  "doc_as_upsert": true
}

Run `POST test/_update/1` to use a script to add a tag to a list of tags. In this example, it is just a list, so the tag is added even it exists.

{
  "script": {
    "source": "ctx._source.tags.add(params.tag)",
    "lang": "painless",
    "params": {
      "tag": "blue"
    }
  }
}

Run `POST test/_update/1` to use a script to remove a tag from a list of tags. The Painless function to remove a tag takes the array index of the element you want to remove. To avoid a possible runtime error, you first need to make sure the tag exists. If the list contains duplicates of the tag, this script just removes one occurrence.

{
  "script": {
    "source": "if (ctx._source.tags.contains(params.tag)) { ctx._source.tags.remove(ctx._source.tags.indexOf(params.tag)) }",
    "lang": "painless",
    "params": {
      "tag": "blue"
    }
  }
}

Run `POST test/_update/1` to use a script to add a field `new_field` to the document.

{
  "script" : "ctx._source.new_field = 'value_of_new_field'"
}

Run `POST test/_update/1` to use a script to remove a field `new_field` from the document.

{
  "script" : "ctx._source.remove('new_field')"
}

Run `POST test/_update/1` to use a script to remove a subfield from an object field.

{
  "script": "ctx._source['my-object'].remove('my-subfield')"
}

Run `POST test/_update/1` to change the operation that runs from within the script. For example, this request deletes the document if the `tags` field contains `green`, otherwise it does nothing (`noop`).

{
  "script": {
    "source": "if (ctx._source.tags.contains(params.tag)) { ctx.op = 'delete' } else { ctx.op = 'noop' }",
    "lang": "painless",
    "params": {
      "tag": "green"
    }
  }
}

Run `POST test/_update/1` to do a partial update that adds a new field to the existing document.

{
  "doc": {
    "name": "new_name"
  }
}

Run `POST test/_update/1` to perfom an upsert. If the document does not already exist, the contents of the upsert element are inserted as a new document. If the document exists, the script is run.

{
  "script": {
    "source": "ctx._source.counter += params.count",
    "lang": "painless",
    "params": {
      "count": 4
    }
  },
  "upsert": {
    "counter": 1
  }
}

Response examples (200)

By default updates that don't change anything detect that they don't change anything and return `"result": "noop"`.

{
   "_shards": {
        "total": 0,
        "successful": 0,
        "failed": 0
   },
   "_index": "test",
   "_id": "1",
   "_version": 2,
   "_primary_term": 1,
   "_seq_no": 1,
   "result": "noop"
}

Delete an enrich policy Added in 7.5.0

DELETE /_enrich/policy/{name}

Api key auth Basic auth Bearer auth

Deletes an existing enrich policy and its enrich index.

Path parameters

name string Required

Enrich policy to delete.

Query parameters

master_timeout string

Period to wait for a connection to the master node.

Responses

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

DELETE /_enrich/policy/{name}

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

Response examples (200)

{
  "acknowledged": true
}

Run multiple Fleet searches Technical preview

GET /{index}/_fleet/_fleet_msearch

Api key auth Basic auth Bearer auth

Run several Fleet searches with a single API request. The API follows the same structure as the multi search API. However, similar to the Fleet search API, it supports the wait_for_checkpoints parameter.

Path parameters

index string Required

A single target to search. If the target is an index alias, it must resolve to a single index.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
ccs_minimize_roundtrips boolean

If true, network roundtrips between the coordinating node and remote clusters are minimized for cross-cluster search requests.
expand_wildcards string | array[string]

Type of index that wildcard expressions can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
ignore_throttled boolean

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

If true, missing or closed indices are not included in the response.
max_concurrent_searches number

Maximum number of concurrent searches the multi search API can execute.
max_concurrent_shard_requests number

Maximum number of concurrent shard requests that each sub-search request executes per node.
pre_filter_shard_size number

Defines a threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method i.e., if date filters are mandatory to match but the shard bounds and the query are disjoint.
search_type string

Indicates whether global term and document frequencies should be used when scoring returned documents.

Values are query_then_fetch or dfs_query_then_fetch.
rest_total_hits_as_int boolean

If true, hits.total are returned as an integer in the response. Defaults to false, which returns an object.
typed_keys boolean

Specifies whether aggregation and suggester names should be prefixed by their respective types in the response.
wait_for_checkpoints array[number]

A comma separated list of checkpoints. When configured, the search API will only be executed on a shard after the relevant checkpoint has become visible for search. Defaults to an empty list which will cause Elasticsearch to immediately execute the search.
allow_partial_search_results boolean

If true, returns partial results if there are shard request timeouts or shard failures. If false, returns an error with no partial results. Defaults to the configured cluster setting search.default_allow_partial_results, which is true by default.

application/json

Body object Required

allow_no_indices boolean
expand_wildcards string | array[string]
ignore_unavailable boolean
index string | array[string]
preference string
request_cache boolean
routing string
search_type string

Values are query_then_fetch or dfs_query_then_fetch.
ccs_minimize_roundtrips boolean
allow_partial_search_results boolean
ignore_throttled boolean

aggregations object

Defines the aggregations that are run as part of the search request.

External documentation
collapse object
Hide collapse attributes Show collapse attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- inner_hits object | array[object]
  
  The number of inner hits and their sort order
  
  One of:
  InnerHits object array-2 array[object]
  
  Hide attributes Show attributes
  
  name string
  
  size number
  
  The maximum number of hits to return per inner_hits.
  
  from number
  
  Inner hit starting document offset.
  
  collapse object
  
  docvalue_fields array[object]
  
  explain boolean
  
  highlight object
  
  ignore_unmapped boolean
  
  script_fields object
  
  Hide script_fields attribute Show script_fields attribute object
  
  * object Additional properties
  
  seq_no_primary_term boolean
  
  fields string | array[string]
  
  sort array[string | object]
  
  _source boolean | object
  
  Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
  
  One of:
  SourceConfig boolean SourceFilter object
  
  stored_fields string | array[string]
  
  track_scores boolean
  
  version boolean
  
  Hide attributes Show attributes object
  
  name string
  
  size number
  
  The maximum number of hits to return per inner_hits.
  
  from number
  
  Inner hit starting document offset.
  
  collapse object
  
  docvalue_fields array[object]
  
  explain boolean
  
  highlight
  
  ignore_unmapped boolean
  
  script_fields object
  
  seq_no_primary_term boolean
  
  fields string | array[string]
  
  sort
  
  _source
  
  stored_fields string | array[string]
  
  track_scores boolean
  
  version boolean
- max_concurrent_group_searches number
  
  The number of concurrent requests allowed to retrieve the inner_hits per group
- collapse object
explain boolean

If true, the request returns detailed information about score computation as part of a hit.
ext object

Configuration of search extensions defined by Elasticsearch plugins.
Hide ext attribute Show ext attribute object
- * object Additional properties
from number

The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
highlight object
Hide highlight attributes Show highlight attributes object
- type string
 
 Any of:
 HighlighterType string HighlighterType string
 
 Values are plain, fvh, or unified.
- boundary_chars string
 
 A string that contains each boundary character.
- boundary_max_scan number
 
 How far to scan for boundary characters.
- boundary_scanner string
 
 Values are chars, sentence, or word.
- boundary_scanner_locale string
 
 Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".
- force_source boolean Deprecated
- fragmenter string
 
 Values are simple or span.
- fragment_size number
 
 The size of the highlighted fragment in characters.
- highlight_filter boolean
- highlight_query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
- max_fragment_length number
- max_analyzed_offset number
 
 If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.
- no_match_size number
 
 The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
- number_of_fragments number
 
 The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.
- options object
 Hide options attribute Show options attribute object
 
 * object Additional properties
- order string
 
 Value is score.
- phrase_limit number
 
 Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.
- post_tags array[string]
 
 Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
- pre_tags array[string]
 
 Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
- require_field_match boolean
 
 By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.
- tags_schema string
 
 Value is styled.
- encoder string
 
 Values are default or html.
- fields object Required
track_total_hits boolean | number

Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
indices_boost array[object]

Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.

External documentation
Hide indices_boost attribute Show indices_boost attribute object
- * number Additional properties
docvalue_fields array[object]

An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.

External documentation
Hide docvalue_fields attributes Show docvalue_fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
knn object | array[object]

The approximate kNN search to run.
One of:
KnnSearch object array-2 array[object]
Hide attributes Show attributes

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

query_vector array[number]

query_vector_builder object

Hide query_vector_builder attribute Show query_vector_builder attribute object

text_embedding object

Hide text_embedding attributes Show text_embedding attributes object

model_id string Required

model_text string Required

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter object | array[object]

Filters for the kNN search query

One of:
QueryContainer object array-2 array[object]

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

External documentation

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

Hide inner_hits attributes Show inner_hits attributes object

name string

size number

The maximum number of hits to return per inner_hits.

from number

Inner hit starting document offset.

collapse object

Hide collapse attributes Show collapse attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

inner_hits

max_concurrent_group_searches number

The number of concurrent requests allowed to retrieve the inner_hits per group

collapse object

docvalue_fields array[object]

explain boolean

highlight object

ignore_unmapped boolean

script_fields object

Hide script_fields attribute Show script_fields attribute object

* object Additional properties

seq_no_primary_term boolean

fields string | array[string]

sort array[string | object]

_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.

One of:
SourceConfig boolean SourceFilter object

stored_fields string | array[string]

track_scores boolean

version boolean

rescore_vector object

Hide rescore_vector attribute Show rescore_vector attribute object

oversample number Required

Applies the specified oversample factor to k on the approximate kNN search
External documentation
Hide attributes Show attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

query_vector array[number]

query_vector_builder object

Hide query_vector_builder attribute Show query_vector_builder attribute object

text_embedding object

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter object | array[object]

Filters for the kNN search query

One of:
QueryContainer object array-2 array[object]

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

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

Hide inner_hits attributes Show inner_hits attributes object

name string

size number

The maximum number of hits to return per inner_hits.

from number

Inner hit starting document offset.

collapse object

docvalue_fields array[object]

explain boolean

highlight

ignore_unmapped boolean

script_fields object

seq_no_primary_term boolean

fields string | array[string]

sort

_source

stored_fields string | array[string]

track_scores boolean

version boolean

rescore_vector object

Hide rescore_vector attribute Show rescore_vector attribute object

oversample number Required

Applies the specified oversample factor to k on the approximate kNN search
rank object
Hide rank attribute Show rank attribute object
- rrf object
  Hide rrf attributes Show rrf attributes object
  
  rank_constant number
  
  How much influence documents in individual result sets per query have over the final ranked result set
  
  rank_window_size number
  
  Size of the individual result sets per query
min_score number

The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
post_filter object

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

External documentation
profile boolean

Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
query object

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

External documentation
rescore object | array[object]

Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the query and post_filter phases.
One of:
Rescore object array-2 array[object]
Hide attributes Show attributes

window_size number

query object

Hide query attributes Show query attributes object

rescore_query object Required

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

query_weight number

Relative importance of the original query versus the rescore query.

rescore_query_weight number

Relative importance of the rescore query versus the original query.

score_mode string

Values are avg, max, min, multiply, or total.

learning_to_rank object

Hide learning_to_rank attributes Show learning_to_rank attributes object

model_id string Required

The unique identifier of the trained model uploaded to Elasticsearch

params object

Named parameters to be passed to the query templates used for feature
Hide attributes Show attributes object

window_size number

query object

learning_to_rank object
retriever object
Hide retriever attributes Show retriever attributes object
- standard object
  Hide standard attributes Show standard attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  terminate_after number
  
  Maximum number of documents to collect for each shard.
  
  sort array[string | object]
  
  collapse object
  
  Hide collapse attributes Show collapse attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  inner_hits
  
  max_concurrent_group_searches number
  
  The number of concurrent requests allowed to retrieve the inner_hits per group
  
  collapse object
- knn object
  Hide knn attributes Show knn attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  field string Required
  
  The name of the vector field to search against.
  
  query_vector array[number]
  
  query_vector_builder object
  
  Hide query_vector_builder attribute Show query_vector_builder attribute object
  
  text_embedding object
  
  k number Required
  
  Number of nearest neighbors to return as top hits.
  
  num_candidates number Required
  
  Number of nearest neighbor candidates to consider per shard.
  
  similarity number
  
  The minimum similarity required for a document to be considered a match.
  
  rescore_vector object
  
  Hide rescore_vector attribute Show rescore_vector attribute object
  
  oversample number Required
  
  Applies the specified oversample factor to k on the approximate kNN search
- rrf object
  Hide rrf attributes Show rrf attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  retrievers array[object] Required
  
  A list of child retrievers to specify which sets of returned top documents will have the RRF formula applied to them.
  
  rank_constant number
  
  This value determines how much influence documents in individual result sets per query have over the final ranked result set.
  
  rank_window_size number
  
  This value determines the size of the individual result sets per query.
- text_similarity_reranker object
  Hide text_similarity_reranker attributes Show text_similarity_reranker attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  retriever object Required
  
  rank_window_size number
  
  This value determines how many documents we will consider from the nested retriever.
  
  inference_id string
  
  Unique identifier of the inference endpoint created using the inference API.
  
  inference_text string
  
  The text snippet used as the basis for similarity comparison
  
  field string
  
  The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text
- rule object
  Hide rule attributes Show rule attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  ruleset_ids array[string] Required
  
  The ruleset IDs containing the rules this retriever is evaluating against.
  
  match_criteria object Required
  
  The match criteria that will determine if a rule in the provided rulesets should be applied.
  
  retriever object Required
  
  rank_window_size number
  
  This value determines the size of the individual result set.
script_fields object

Retrieve a script evaluation (based on different fields) for each hit.
Hide script_fields attribute Show script_fields attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  script object Required
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string ScriptSource object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  ignore_failure boolean
search_after array[number | string | boolean | null]

A field value.
size number

The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.
slice object
Hide slice attributes Show slice attributes object
- field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- id string Required
- max number Required
sort string | object | array[string | object]
One of:
Field string SortOptions object Sort array[string | object]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Hide attributes Show attributes

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

Values are min, max, sum, avg, or median.

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

Values are in, ft, yd, mi, nmi, km, m, cm, or mm.

nested object

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

type string

Values are string, number, or version.

mode string

Values are min, max, sum, avg, or median.

nested object
One of:
Field string SortOptions object

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
One of:
SourceConfig boolean SourceFilter object
Hide attributes Show attributes

excludes string | array[string]

includes string | array[string]
fields array[object]

An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
Hide fields attributes Show fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
suggest object
Hide suggest attribute Show suggest attribute object
- text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters
terminate_after number

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

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

If set to 0 (default), the query does not terminate early.
timeout string

The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
track_scores boolean

If true, calculate and return document scores, even if the scores are not used for sorting.
version boolean

If true, the request returns the document version as part of a hit.
seq_no_primary_term boolean

If true, the request returns sequence number and primary term of the last modification of each hit.

External documentation
stored_fields string | array[string]
pit object
Hide pit attributes Show pit attributes object
- id string Required
- keep_alive string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string ScriptSource object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
stats array[string]

The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.

Responses

200 application/json
Hide response attribute Show response attribute object
- docs array[object] Required
  
  One of:
  MultiSearchItem object ErrorResponseBase object
  
  Hide attributes Show attributes
  
  took number Required
  
  The number of milliseconds it took Elasticsearch to run the request. This value is calculated by measuring the time elapsed between receipt of a request on the coordinating node and the time at which the coordinating node is ready to send the response. It includes:
  
  Communication time between the coordinating node and data nodes
  
  Time the request spends in the search thread pool, queued for execution
  
  Actual run time
  
  It does not include:
  
  Time needed to send the request to Elasticsearch
  
  Time needed to serialize the JSON response
  
  Time needed to send the response to a client
  
  timed_out boolean Required
  
  If true, the request timed out before completion; returned results may be partial or empty.
  
  _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  skipped number
  
  hits object Required
  
  Hide hits attributes Show hits attributes object
  
  total
  
  hits array[object] Required
  
  max_score
  
  aggregations object
  
  _clusters object
  
  Hide _clusters attributes Show _clusters attributes object
  
  skipped number Required
  
  successful number Required
  
  total number Required
  
  running number Required
  
  partial number Required
  
  failed number Required
  
  details object
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  max_score number
  
  num_reduce_phases number
  
  profile object
  
  Hide profile attribute Show profile attribute object
  
  shards array[object] Required
  
  pit_id string
  
  _scroll_id string
  
  suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  * array[object] Additional properties
  
  terminated_early boolean
  
  status number
  
  Hide attributes Show attributes
  
  error object Required
  
  Hide error attributes Show error attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  status number Required

GET /{index}/_fleet/_fleet_msearch

curl \
 --request GET 'http://api.example.com/{index}/_fleet/_fleet_msearch' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '[{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"index":"string","preference":"string","request_cache":true,"routing":"string","search_type":"query_then_fetch","ccs_minimize_roundtrips":true,"allow_partial_search_results":true,"ignore_throttled":true}]'

Request examples

[
  {
    "allow_no_indices": true,
    "expand_wildcards": "string",
    "ignore_unavailable": true,
    "index": "string",
    "preference": "string",
    "request_cache": true,
    "routing": "string",
    "search_type": "query_then_fetch",
    "ccs_minimize_roundtrips": true,
    "allow_partial_search_results": true,
    "ignore_throttled": true
  }
]

Response examples (200)

{
  "docs": [
    {
      "took": 42.0,
      "timed_out": true,
      "_shards": {
        "failed": 42.0,
        "successful": 42.0,
        "total": 42.0,
        "failures": [
          {}
        ],
        "skipped": 42.0
      },
      "hits": {
        "hits": [
          {}
        ]
      },
      "aggregations": {},
      "_clusters": {
        "skipped": 42.0,
        "successful": 42.0,
        "total": 42.0,
        "running": 42.0,
        "partial": 42.0,
        "failed": 42.0,
        "details": {}
      },
      "fields": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      },
      "max_score": 42.0,
      "num_reduce_phases": 42.0,
      "profile": {
        "shards": [
          {}
        ]
      },
      "pit_id": "string",
      "_scroll_id": "string",
      "suggest": {
        "additionalProperty1": [
          {}
        ],
        "additionalProperty2": [
          {}
        ]
      },
      "terminated_early": true,
      "status": 42.0
    }
  ]
}

Run multiple Fleet searches Technical preview

POST /{index}/_fleet/_fleet_msearch

Api key auth Basic auth Bearer auth

Run several Fleet searches with a single API request. The API follows the same structure as the multi search API. However, similar to the Fleet search API, it supports the wait_for_checkpoints parameter.

Path parameters

index string Required

A single target to search. If the target is an index alias, it must resolve to a single index.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
ccs_minimize_roundtrips boolean

If true, network roundtrips between the coordinating node and remote clusters are minimized for cross-cluster search requests.
expand_wildcards string | array[string]

Type of index that wildcard expressions can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
ignore_throttled boolean

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

If true, missing or closed indices are not included in the response.
max_concurrent_searches number

Maximum number of concurrent searches the multi search API can execute.
max_concurrent_shard_requests number

Maximum number of concurrent shard requests that each sub-search request executes per node.
pre_filter_shard_size number

Defines a threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method i.e., if date filters are mandatory to match but the shard bounds and the query are disjoint.
search_type string

Indicates whether global term and document frequencies should be used when scoring returned documents.

Values are query_then_fetch or dfs_query_then_fetch.
rest_total_hits_as_int boolean

If true, hits.total are returned as an integer in the response. Defaults to false, which returns an object.
typed_keys boolean

Specifies whether aggregation and suggester names should be prefixed by their respective types in the response.
wait_for_checkpoints array[number]

A comma separated list of checkpoints. When configured, the search API will only be executed on a shard after the relevant checkpoint has become visible for search. Defaults to an empty list which will cause Elasticsearch to immediately execute the search.
allow_partial_search_results boolean

If true, returns partial results if there are shard request timeouts or shard failures. If false, returns an error with no partial results. Defaults to the configured cluster setting search.default_allow_partial_results, which is true by default.

application/json

Body object Required

allow_no_indices boolean
expand_wildcards string | array[string]
ignore_unavailable boolean
index string | array[string]
preference string
request_cache boolean
routing string
search_type string

Values are query_then_fetch or dfs_query_then_fetch.
ccs_minimize_roundtrips boolean
allow_partial_search_results boolean
ignore_throttled boolean

aggregations object

Defines the aggregations that are run as part of the search request.

External documentation
collapse object
Hide collapse attributes Show collapse attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- inner_hits object | array[object]
  
  The number of inner hits and their sort order
  
  One of:
  InnerHits object array-2 array[object]
  
  Hide attributes Show attributes
  
  name string
  
  size number
  
  The maximum number of hits to return per inner_hits.
  
  from number
  
  Inner hit starting document offset.
  
  collapse object
  
  docvalue_fields array[object]
  
  explain boolean
  
  highlight object
  
  ignore_unmapped boolean
  
  script_fields object
  
  Hide script_fields attribute Show script_fields attribute object
  
  * object Additional properties
  
  seq_no_primary_term boolean
  
  fields string | array[string]
  
  sort array[string | object]
  
  _source boolean | object
  
  Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
  
  One of:
  SourceConfig boolean SourceFilter object
  
  stored_fields string | array[string]
  
  track_scores boolean
  
  version boolean
  
  Hide attributes Show attributes object
  
  name string
  
  size number
  
  The maximum number of hits to return per inner_hits.
  
  from number
  
  Inner hit starting document offset.
  
  collapse object
  
  docvalue_fields array[object]
  
  explain boolean
  
  highlight
  
  ignore_unmapped boolean
  
  script_fields object
  
  seq_no_primary_term boolean
  
  fields string | array[string]
  
  sort
  
  _source
  
  stored_fields string | array[string]
  
  track_scores boolean
  
  version boolean
- max_concurrent_group_searches number
  
  The number of concurrent requests allowed to retrieve the inner_hits per group
- collapse object
explain boolean

If true, the request returns detailed information about score computation as part of a hit.
ext object

Configuration of search extensions defined by Elasticsearch plugins.
Hide ext attribute Show ext attribute object
- * object Additional properties
from number

The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
highlight object
Hide highlight attributes Show highlight attributes object
- type string
 
 Any of:
 HighlighterType string HighlighterType string
 
 Values are plain, fvh, or unified.
- boundary_chars string
 
 A string that contains each boundary character.
- boundary_max_scan number
 
 How far to scan for boundary characters.
- boundary_scanner string
 
 Values are chars, sentence, or word.
- boundary_scanner_locale string
 
 Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".
- force_source boolean Deprecated
- fragmenter string
 
 Values are simple or span.
- fragment_size number
 
 The size of the highlighted fragment in characters.
- highlight_filter boolean
- highlight_query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
- max_fragment_length number
- max_analyzed_offset number
 
 If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.
- no_match_size number
 
 The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
- number_of_fragments number
 
 The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.
- options object
 Hide options attribute Show options attribute object
 
 * object Additional properties
- order string
 
 Value is score.
- phrase_limit number
 
 Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.
- post_tags array[string]
 
 Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
- pre_tags array[string]
 
 Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
- require_field_match boolean
 
 By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.
- tags_schema string
 
 Value is styled.
- encoder string
 
 Values are default or html.
- fields object Required
track_total_hits boolean | number

Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
indices_boost array[object]

Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.

External documentation
Hide indices_boost attribute Show indices_boost attribute object
- * number Additional properties
docvalue_fields array[object]

An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.

External documentation
Hide docvalue_fields attributes Show docvalue_fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
knn object | array[object]

The approximate kNN search to run.
One of:
KnnSearch object array-2 array[object]
Hide attributes Show attributes

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

query_vector array[number]

query_vector_builder object

Hide query_vector_builder attribute Show query_vector_builder attribute object

text_embedding object

Hide text_embedding attributes Show text_embedding attributes object

model_id string Required

model_text string Required

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter object | array[object]

Filters for the kNN search query

One of:
QueryContainer object array-2 array[object]

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

External documentation

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

Hide inner_hits attributes Show inner_hits attributes object

name string

size number

The maximum number of hits to return per inner_hits.

from number

Inner hit starting document offset.

collapse object

Hide collapse attributes Show collapse attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

inner_hits

max_concurrent_group_searches number

The number of concurrent requests allowed to retrieve the inner_hits per group

collapse object

docvalue_fields array[object]

explain boolean

highlight object

ignore_unmapped boolean

script_fields object

Hide script_fields attribute Show script_fields attribute object

* object Additional properties

seq_no_primary_term boolean

fields string | array[string]

sort array[string | object]

_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.

One of:
SourceConfig boolean SourceFilter object

stored_fields string | array[string]

track_scores boolean

version boolean

rescore_vector object

Hide rescore_vector attribute Show rescore_vector attribute object

oversample number Required

Applies the specified oversample factor to k on the approximate kNN search
External documentation
Hide attributes Show attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

query_vector array[number]

query_vector_builder object

Hide query_vector_builder attribute Show query_vector_builder attribute object

text_embedding object

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter object | array[object]

Filters for the kNN search query

One of:
QueryContainer object array-2 array[object]

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

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

Hide inner_hits attributes Show inner_hits attributes object

name string

size number

The maximum number of hits to return per inner_hits.

from number

Inner hit starting document offset.

collapse object

docvalue_fields array[object]

explain boolean

highlight

ignore_unmapped boolean

script_fields object

seq_no_primary_term boolean

fields string | array[string]

sort

_source

stored_fields string | array[string]

track_scores boolean

version boolean

rescore_vector object

Hide rescore_vector attribute Show rescore_vector attribute object

oversample number Required

Applies the specified oversample factor to k on the approximate kNN search
rank object
Hide rank attribute Show rank attribute object
- rrf object
  Hide rrf attributes Show rrf attributes object
  
  rank_constant number
  
  How much influence documents in individual result sets per query have over the final ranked result set
  
  rank_window_size number
  
  Size of the individual result sets per query
min_score number

The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
post_filter object

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

External documentation
profile boolean

Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
query object

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

External documentation
rescore object | array[object]

Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the query and post_filter phases.
One of:
Rescore object array-2 array[object]
Hide attributes Show attributes

window_size number

query object

Hide query attributes Show query attributes object

rescore_query object Required

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

query_weight number

Relative importance of the original query versus the rescore query.

rescore_query_weight number

Relative importance of the rescore query versus the original query.

score_mode string

Values are avg, max, min, multiply, or total.

learning_to_rank object

Hide learning_to_rank attributes Show learning_to_rank attributes object

model_id string Required

The unique identifier of the trained model uploaded to Elasticsearch

params object

Named parameters to be passed to the query templates used for feature
Hide attributes Show attributes object

window_size number

query object

learning_to_rank object
retriever object
Hide retriever attributes Show retriever attributes object
- standard object
  Hide standard attributes Show standard attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  terminate_after number
  
  Maximum number of documents to collect for each shard.
  
  sort array[string | object]
  
  collapse object
  
  Hide collapse attributes Show collapse attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  inner_hits
  
  max_concurrent_group_searches number
  
  The number of concurrent requests allowed to retrieve the inner_hits per group
  
  collapse object
- knn object
  Hide knn attributes Show knn attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  field string Required
  
  The name of the vector field to search against.
  
  query_vector array[number]
  
  query_vector_builder object
  
  Hide query_vector_builder attribute Show query_vector_builder attribute object
  
  text_embedding object
  
  k number Required
  
  Number of nearest neighbors to return as top hits.
  
  num_candidates number Required
  
  Number of nearest neighbor candidates to consider per shard.
  
  similarity number
  
  The minimum similarity required for a document to be considered a match.
  
  rescore_vector object
  
  Hide rescore_vector attribute Show rescore_vector attribute object
  
  oversample number Required
  
  Applies the specified oversample factor to k on the approximate kNN search
- rrf object
  Hide rrf attributes Show rrf attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  retrievers array[object] Required
  
  A list of child retrievers to specify which sets of returned top documents will have the RRF formula applied to them.
  
  rank_constant number
  
  This value determines how much influence documents in individual result sets per query have over the final ranked result set.
  
  rank_window_size number
  
  This value determines the size of the individual result sets per query.
- text_similarity_reranker object
  Hide text_similarity_reranker attributes Show text_similarity_reranker attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  retriever object Required
  
  rank_window_size number
  
  This value determines how many documents we will consider from the nested retriever.
  
  inference_id string
  
  Unique identifier of the inference endpoint created using the inference API.
  
  inference_text string
  
  The text snippet used as the basis for similarity comparison
  
  field string
  
  The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text
- rule object
  Hide rule attributes Show rule attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  ruleset_ids array[string] Required
  
  The ruleset IDs containing the rules this retriever is evaluating against.
  
  match_criteria object Required
  
  The match criteria that will determine if a rule in the provided rulesets should be applied.
  
  retriever object Required
  
  rank_window_size number
  
  This value determines the size of the individual result set.
script_fields object

Retrieve a script evaluation (based on different fields) for each hit.
Hide script_fields attribute Show script_fields attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  script object Required
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string ScriptSource object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  ignore_failure boolean
search_after array[number | string | boolean | null]

A field value.
size number

The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.
slice object
Hide slice attributes Show slice attributes object
- field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- id string Required
- max number Required
sort string | object | array[string | object]
One of:
Field string SortOptions object Sort array[string | object]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Hide attributes Show attributes

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

Values are min, max, sum, avg, or median.

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

Values are in, ft, yd, mi, nmi, km, m, cm, or mm.

nested object

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

type string

Values are string, number, or version.

mode string

Values are min, max, sum, avg, or median.

nested object
One of:
Field string SortOptions object

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
One of:
SourceConfig boolean SourceFilter object
Hide attributes Show attributes

excludes string | array[string]

includes string | array[string]
fields array[object]

An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
Hide fields attributes Show fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
suggest object
Hide suggest attribute Show suggest attribute object
- text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters
terminate_after number

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

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

If set to 0 (default), the query does not terminate early.
timeout string

The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
track_scores boolean

If true, calculate and return document scores, even if the scores are not used for sorting.
version boolean

If true, the request returns the document version as part of a hit.
seq_no_primary_term boolean

If true, the request returns sequence number and primary term of the last modification of each hit.

External documentation
stored_fields string | array[string]
pit object
Hide pit attributes Show pit attributes object
- id string Required
- keep_alive string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string ScriptSource object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
stats array[string]

The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.

Responses

200 application/json
Hide response attribute Show response attribute object
- docs array[object] Required
  
  One of:
  MultiSearchItem object ErrorResponseBase object
  
  Hide attributes Show attributes
  
  took number Required
  
  The number of milliseconds it took Elasticsearch to run the request. This value is calculated by measuring the time elapsed between receipt of a request on the coordinating node and the time at which the coordinating node is ready to send the response. It includes:
  
  Communication time between the coordinating node and data nodes
  
  Time the request spends in the search thread pool, queued for execution
  
  Actual run time
  
  It does not include:
  
  Time needed to send the request to Elasticsearch
  
  Time needed to serialize the JSON response
  
  Time needed to send the response to a client
  
  timed_out boolean Required
  
  If true, the request timed out before completion; returned results may be partial or empty.
  
  _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  skipped number
  
  hits object Required
  
  Hide hits attributes Show hits attributes object
  
  total
  
  hits array[object] Required
  
  max_score
  
  aggregations object
  
  _clusters object
  
  Hide _clusters attributes Show _clusters attributes object
  
  skipped number Required
  
  successful number Required
  
  total number Required
  
  running number Required
  
  partial number Required
  
  failed number Required
  
  details object
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  max_score number
  
  num_reduce_phases number
  
  profile object
  
  Hide profile attribute Show profile attribute object
  
  shards array[object] Required
  
  pit_id string
  
  _scroll_id string
  
  suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  * array[object] Additional properties
  
  terminated_early boolean
  
  status number
  
  Hide attributes Show attributes
  
  error object Required
  
  Hide error attributes Show error attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  status number Required

POST /{index}/_fleet/_fleet_msearch

curl \
 --request POST 'http://api.example.com/{index}/_fleet/_fleet_msearch' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '[{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"index":"string","preference":"string","request_cache":true,"routing":"string","search_type":"query_then_fetch","ccs_minimize_roundtrips":true,"allow_partial_search_results":true,"ignore_throttled":true}]'

Request examples

[
  {
    "allow_no_indices": true,
    "expand_wildcards": "string",
    "ignore_unavailable": true,
    "index": "string",
    "preference": "string",
    "request_cache": true,
    "routing": "string",
    "search_type": "query_then_fetch",
    "ccs_minimize_roundtrips": true,
    "allow_partial_search_results": true,
    "ignore_throttled": true
  }
]

Response examples (200)

{
  "docs": [
    {
      "took": 42.0,
      "timed_out": true,
      "_shards": {
        "failed": 42.0,
        "successful": 42.0,
        "total": 42.0,
        "failures": [
          {}
        ],
        "skipped": 42.0
      },
      "hits": {
        "hits": [
          {}
        ]
      },
      "aggregations": {},
      "_clusters": {
        "skipped": 42.0,
        "successful": 42.0,
        "total": 42.0,
        "running": 42.0,
        "partial": 42.0,
        "failed": 42.0,
        "details": {}
      },
      "fields": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      },
      "max_score": 42.0,
      "num_reduce_phases": 42.0,
      "profile": {
        "shards": [
          {}
        ]
      },
      "pit_id": "string",
      "_scroll_id": "string",
      "suggest": {
        "additionalProperty1": [
          {}
        ],
        "additionalProperty2": [
          {}
        ]
      },
      "terminated_early": true,
      "status": 42.0
    }
  ]
}

Get index templates Added in 7.9.0

GET /_index_template/{name}

Api key auth Basic auth Bearer auth

Get information about one or more index templates.

Path parameters

name string Required

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

Query parameters

local boolean

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

If true, returns settings in flat format.
master_timeout string

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

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

Responses

200 application/json
Hide response attribute Show response attribute object
- index_templates array[object] Required
  
  Hide index_templates attributes Show index_templates attributes object
  
  name string Required
  
  index_template object Required
  
  Hide index_template attributes Show index_template attributes object
  
  index_patterns string | array[string] Required
  
  composed_of array[string] Required
  
  An ordered list of component template names. Component templates are merged in the order specified, meaning that the last component template specified has the highest precedence.
  
  template object
  
  Hide template attributes Show template attributes object
  
  aliases object
  
  Aliases to add. If the index template includes a data_stream object, these are data stream aliases. Otherwise, these are index aliases. Data stream aliases ignore the index_routing, routing, and search_routing options.
  
  Hide aliases attribute Show aliases attribute object
  
  * object Additional properties
  
  mappings object
  
  Hide mappings attributes Show mappings attributes object
  
  all_field object
  
  date_detection boolean
  
  dynamic string
  
  Values are strict, runtime, true, or false.
  
  dynamic_date_formats array[string]
  
  dynamic_templates array[object]
  
  _field_names object
  
  index_field object
  
  _meta object
  
  numeric_detection boolean
  
  properties object
  
  _routing object
  
  _size object
  
  _source object
  
  runtime object
  
  enabled boolean
  
  subobjects string
  
  Values are true, false, or auto.
  
  _data_stream_timestamp object
  
  settings object
  
  Hide settings attributes Show settings attributes object
  
  index object
  
  mode string
  
  routing_path
  
  soft_deletes object
  
  sort object
  
  number_of_shards
  
  number_of_replicas
  
  number_of_routing_shards number
  
  check_on_startup string
  
  Values are true, false, or checksum.
  
  codec string
  
  routing_partition_size
  
  load_fixed_bitset_filters_eagerly boolean
  
  hidden
  
  auto_expand_replicas
  
  merge object
  
  search object
  
  refresh_interval string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  max_result_window number
  
  max_inner_result_window number
  
  max_rescore_window number
  
  max_docvalue_fields_search number
  
  max_script_fields number
  
  max_ngram_diff number
  
  max_shingle_diff number
  
  blocks object
  
  max_refresh_listeners number
  
  analyze object
  
  highlight object
  
  max_terms_count number
  
  max_regex_length number
  
  routing object
  
  gc_deletes string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  default_pipeline string
  
  final_pipeline string
  
  lifecycle object
  
  provided_name string
  
  creation_date
  
  creation_date_string
  
  uuid string
  
  version object
  
  verified_before_close
  
  format
  
  max_slices_per_scroll number
  
  translog object
  
  query_string object
  
  priority
  
  top_metrics_max_size number
  
  analysis object
  
  settings object
  
  time_series object
  
  queries object
  
  similarity object
  
  Configure custom similarity settings to customize how search results are scored.
  
  mapping object
  
  indexing.slowlog object
  
  indexing_pressure object
  
  store object
  
  lifecycle object
  
  version number
  
  priority number
  
  Priority to determine index template precedence when a new data stream or index is created. The index template with the highest priority is chosen. If no priority is specified the template is treated as though it is of priority 0 (lowest priority). This number is not automatically generated by Elasticsearch.
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
  
  allow_auto_create boolean
  
  data_stream object
  
  Hide data_stream attributes Show data_stream attributes object
  
  hidden boolean
  
  If true, the data stream is hidden.
  
  allow_custom_routing boolean
  
  If true, the data stream supports custom routing.
  
  deprecated boolean
  
  Marks this index template as deprecated. When creating or updating a non-deprecated index template that uses deprecated components, Elasticsearch will emit a deprecation warning.
  
  ignore_missing_component_templates string | array[string]

GET /_index_template/{name}

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

Response examples (200)

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

Flush data streams or indices

POST /{index}/_flush

Api key auth Basic auth Bearer auth

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

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

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

Path parameters

index string | array[string] Required

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

Query parameters

allow_no_indices boolean

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

Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.
force boolean

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

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

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

Responses

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

POST /{index}/_flush

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

Response examples (200)

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

Update field mappings

PUT /{index}/_mapping

Api key auth Basic auth Bearer auth

Add new fields to an existing data stream or index. You can also use this API to change the search settings of existing fields and add new properties to existing object fields. For data streams, these changes are applied to all backing indices by default.

Add multi-fields to an existing field

Multi-fields let you index the same field in different ways. You can use this API to update the fields mapping parameter and enable multi-fields for an existing field. WARNING: If an index (or data stream) contains documents when you add a multi-field, those documents will not have values for the new multi-field. You can populate the new multi-field with the update by query API.

Change supported mapping parameters for an existing field

The documentation for each mapping parameter indicates whether you can update it for an existing field using this API. For example, you can use the update mapping API to update the ignore_above parameter.

Change the mapping of an existing field

Except for supported mapping parameters, you can't change the mapping or field type of an existing field. Changing an existing field could invalidate data that's already indexed.

If you need to change the mapping of a field in a data stream's backing indices, refer to documentation about modifying data streams. If you need to change the mapping of a field in other indices, create a new index with the correct mapping and reindex your data into that index.

Rename a field

Renaming a field would invalidate data already indexed under the old field name. Instead, add an alias field to create an alternate field name.

External documentation

Path parameters

index string | array[string] Required

A comma-separated list of index names the mapping should be added to (supports wildcards); use _all or omit to add the mapping on all indices.

Query parameters

allow_no_indices boolean

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

Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.
ignore_unavailable boolean

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

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

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

If true, the mappings are applied only to the current write index for the target.

application/json

Body Required

date_detection boolean

Controls whether dynamic date detection is enabled.
dynamic string

Values are strict, runtime, true, or false.
dynamic_date_formats array[string]

If date detection is enabled then new string fields are checked against 'dynamic_date_formats' and if the value matches then a new date field is added instead of string.
dynamic_templates array[object]

Specify dynamic templates for the mapping.
_field_names object
Hide _field_names attribute Show _field_names attribute object
- enabled boolean Required
_meta object
Hide _meta attribute Show _meta attribute object
- * object Additional properties
numeric_detection boolean

Automatically map strings into numeric data types for all fields.
properties object
Mapping for a field. For new fields, this mapping can include:
- Field name
- Field data type
- Mapping parameters
_routing object
Hide _routing attribute Show _routing attribute object
- required boolean Required
_source object
Hide _source attributes Show _source attributes object
- compress boolean
- compress_threshold string
- enabled boolean
- excludes array[string]
- includes array[string]
- mode string
  
  Values are disabled, stored, or synthetic.
runtime object
Hide runtime attribute Show runtime attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string ScriptSource object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.

Responses

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

PUT /{index}/_mapping

curl \
 --request PUT 'http://api.example.com/{index}/_mapping' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"properties\": {\n    \"user\": {\n      \"properties\": {\n        \"name\": {\n          \"type\": \"keyword\"\n        }\n      }\n    }\n  }\n}"'

Request example

The update mapping API can be applied to multiple data streams or indices with a single request. For example, run `PUT /my-index-000001,my-index-000002/_mapping` to update mappings for the `my-index-000001` and `my-index-000002` indices at the same time.

{
  "properties": {
    "user": {
      "properties": {
        "name": {
          "type": "keyword"
        }
      }
    }
  }
}

Response examples (200)

{
  "acknowledged": 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
  }
}

Resolve the cluster Added in 8.13.0

GET /_resolve/cluster

Api key auth Basic auth Bearer auth

Resolve the specified index expressions to return information about each cluster, including the local "querying" cluster, if included. If no index expression is provided, the API will return information about all the remote clusters that are configured on the querying cluster.

This endpoint is useful before doing a cross-cluster search in order to determine which remote clusters should be included in a search.

You use the same index expression with this endpoint as you would for cross-cluster search. Index and cluster exclusions are also supported with this endpoint.

For each cluster in the index expression, information is returned about:

Whether the querying ("local") cluster is currently connected to each remote cluster specified in the index expression. Note that this endpoint actively attempts to contact the remote clusters, unlike the remote/info endpoint.
Whether each remote cluster is configured with skip_unavailable as true or false.
Whether there are any indices, aliases, or data streams on that cluster that match the index expression.
Whether the search is likely to have errors returned when you do the cross-cluster search (including any authorization errors if you do not have permission to query the index).
Cluster version information, including the Elasticsearch server version.

For example, GET /_resolve/cluster/my-index-*,cluster*:my-index-* returns information about the local cluster and all remotely configured clusters that start with the alias cluster*. Each cluster returns information about whether it has any indices, aliases or data streams that match my-index-*.

Note on backwards compatibility

The ability to query without an index expression was added in version 8.18, so when querying remote clusters older than that, the local cluster will send the index expression dummy* to those remote clusters. Thus, if an errors occur, you may see a reference to that index expression even though you didn't request it. If it causes a problem, you can instead include an index expression like *:* to bypass the issue.

Advantages of using this endpoint before a cross-cluster search

You may want to exclude a cluster or index from a search when:

A remote cluster is not currently connected and is configured with skip_unavailable=false. Running a cross-cluster search under those conditions will cause the entire search to fail.
A cluster has no matching indices, aliases or data streams for the index expression (or your user does not have permissions to search them). For example, suppose your index expression is logs*,remote1:logs* and the remote1 cluster has no indices, aliases or data streams that match logs*. In that case, that cluster will return no results from that cluster if you include it in a cross-cluster search.
The index expression (combined with any query parameters you specify) will likely cause an exception to be thrown when you do the search. In these cases, the "error" field in the _resolve/cluster response will be present. (This is also where security/permission errors will be shown.)
A remote cluster is an older version that does not support the feature you want to use in your search.

Test availability of remote clusters

The remote/info endpoint is commonly used to test whether the "local" cluster (the cluster being queried) is connected to its remote clusters, but it does not necessarily reflect whether the remote cluster is available or not. The remote cluster may be available, while the local cluster is not currently connected to it.

You can use the _resolve/cluster API to attempt to reconnect to remote clusters. For example with GET _resolve/cluster or GET _resolve/cluster/*:*. The connected field in the response will indicate whether it was successful. If a connection was (re-)established, this will also cause the remote/info endpoint to now indicate a connected status.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar. NOTE: This option is only supported when specifying an index expression. You will get an error if you specify index options to the _resolve/cluster API endpoint that takes no index expression.
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. NOTE: This option is only supported when specifying an index expression. You will get an error if you specify index options to the _resolve/cluster API endpoint that takes no index expression.
ignore_throttled boolean Deprecated

If true, concrete, expanded, or aliased indices are ignored when frozen. NOTE: This option is only supported when specifying an index expression. You will get an error if you specify index options to the _resolve/cluster API endpoint that takes no index expression.
ignore_unavailable boolean

If false, the request returns an error if it targets a missing or closed index. NOTE: This option is only supported when specifying an index expression. You will get an error if you specify index options to the _resolve/cluster API endpoint that takes no index expression.
timeout string

The maximum time to wait for remote clusters to respond. If a remote cluster does not respond within this timeout period, the API response will show the cluster as not connected and include an error message that the request timed out.

The default timeout is unset and the query can take as long as the networking layer is configured to wait for remote clusters that are not responding (typically 30 seconds).

Responses

200 application/json
Hide response attribute Show response attribute object
- * object Additional properties
  
  Hide * attributes Show * attributes object
  
  connected boolean Required
  
  Whether the remote cluster is connected to the local (querying) cluster.
  
  skip_unavailable boolean Required
  
  The skip_unavailable setting for a remote cluster.
  
  matching_indices boolean
  
  Whether the index expression provided in the request matches any indices, aliases or data streams on the cluster.
  
  error string
  
  Provides error messages that are likely to occur if you do a search with this index expression on the specified cluster (for example, lack of security privileges to query an index).
  
  version object
  
  Hide version attributes Show version attributes object
  
  build_flavor string Required
  
  minimum_index_compatibility_version string Required
  
  minimum_wire_compatibility_version string Required
  
  number string Required

GET /_resolve/cluster

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

Response examples (200)

A successful response from `GET /_resolve/cluster/my-index*,clust*:my-index*`. Each cluster has its own response section. The cluster you sent the request to is labelled as "(local)".

{
  "(local)": {
    "connected": true,
    "skip_unavailable": false,
    "matching_indices": true,
    "version": {
      "number": "8.13.0",
      "build_flavor": "default",
      "minimum_wire_compatibility_version": "7.17.0",
      "minimum_index_compatibility_version": "7.0.0"
    }
  },
  "cluster_one": {
    "connected": true,
    "skip_unavailable": true,
    "matching_indices": true,
    "version": {
      "number": "8.13.0",
      "build_flavor": "default",
      "minimum_wire_compatibility_version": "7.17.0",
      "minimum_index_compatibility_version": "7.0.0"
    }
  },
  "cluster_two": {
    "connected": true,
    "skip_unavailable": false,
    "matching_indices": true,
    "version": {
      "number": "8.13.0",
      "build_flavor": "default",
      "minimum_wire_compatibility_version": "7.17.0",
      "minimum_index_compatibility_version": "7.0.0"
    }
  }
}

A successful response from `GET /_resolve/cluster/not-present,clust*:my-index*,oldcluster:*?ignore_unavailable=false&timeout=5s`. This type of request can be used to identify potential problems with your cross-cluster search. Note also that a `timeout` of 5 seconds is sent, which sets the maximum time the query will wait for remote clusters to respond. The local cluster has no index called `not_present`. Searching with `ignore_unavailable=false` would return a "no such index" error. The `cluster_one` remote cluster has no indices that match the pattern `my-index*`. There may be no indices that match the pattern or the index could be closed. The `cluster_two` remote cluster is not connected (the attempt to connect failed). Since this cluster is marked as `skip_unavailable=false`, you should probably exclude this cluster from the search by adding `-cluster_two:*` to the search index expression. For `cluster_three`, the error message indicates that this remote cluster did not respond within the 5-second timeout window specified, so it is also marked as not connected. The `oldcluster` remote cluster shows that it has matching indices, but no version information is included. This indicates that the cluster version predates the introduction of the `_resolve/cluster` API, so you may want to exclude it from your cross-cluster search.

{
  "(local)": {
    "connected": true,
    "skip_unavailable": false,
    "error": "no such index [not_present]"
  },
  "cluster_one": {
    "connected": true,
    "skip_unavailable": true,
    "matching_indices": false,
    "version": {
      "number": "8.13.0",
      "build_flavor": "default",
      "minimum_wire_compatibility_version": "7.17.0",
      "minimum_index_compatibility_version": "7.0.0"
    }
  },
  "cluster_two": {
    "connected": false,
    "skip_unavailable": false
  },
  "cluster_three": {
    "connected": false,
    "skip_unavailable": false,
    "error": "Request timed out before receiving a response from the remote cluster"
  },
  "oldcluster": {
    "connected": true,
    "skip_unavailable": false,
    "matching_indices": true
  }
}

Create or update an alias Added in 1.3.0

POST /_aliases

Api key auth Basic auth Bearer auth

Adds a data stream or index to an alias.

Query parameters

master_timeout string

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

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

application/json

Body Required

actions array[object]

Actions to perform.
Hide actions attributes Show actions attributes object
- add object
  Hide add attributes Show add attributes object
  
  alias string
  
  aliases string | array[string]
  
  Aliases for the action. Index alias names support date math.
  
  One of:
  IndexAlias string array-2 array[string]
  
  filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  index string
  
  indices string | array[string]
  
  index_routing string
  
  is_hidden boolean
  
  If true, the alias is hidden.
  
  is_write_index boolean
  
  If true, sets the write index or data stream for the alias.
  
  routing string
  
  search_routing string
  
  must_exist boolean
  
  If true, the alias must exist to perform the action.
- remove object
  Hide remove attributes Show remove attributes object
  
  alias string
  
  aliases string | array[string]
  
  Aliases for the action. Index alias names support date math.
  
  One of:
  IndexAlias string array-2 array[string]
  
  index string
  
  indices string | array[string]
  
  must_exist boolean
  
  If true, the alias must exist to perform the action.
- remove_index object
  Hide remove_index attributes Show remove_index attributes object
  
  index string
  
  indices string | array[string]
  
  must_exist boolean
  
  If true, the alias must exist to perform the action.

Responses

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

POST /_aliases

curl \
 --request POST 'http://api.example.com/_aliases' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"actions":[{"add":{"alias":"string","aliases":"string","filter":{},"index":"string","indices":"string","index_routing":"string","is_hidden":true,"is_write_index":true,"routing":"string","search_routing":"string","must_exist":true},"remove":{"alias":"string","aliases":"string","index":"string","indices":"string","must_exist":true},"remove_index":{"index":"string","indices":"string","must_exist":true}}]}'

Request examples

{
  "actions": [
    {
      "add": {
        "alias": "string",
        "aliases": "string",
        "filter": {},
        "index": "string",
        "indices": "string",
        "index_routing": "string",
        "is_hidden": true,
        "is_write_index": true,
        "routing": "string",
        "search_routing": "string",
        "must_exist": true
      },
      "remove": {
        "alias": "string",
        "aliases": "string",
        "index": "string",
        "indices": "string",
        "must_exist": true
      },
      "remove_index": {
        "index": "string",
        "indices": "string",
        "must_exist": true
      }
    }
  ]
}

Response examples (200)

{
  "acknowledged": true
}

Validate a query Added in 1.3.0

GET /{index}/_validate/query

Api key auth Basic auth Bearer auth

Validates a query without running it.

Path parameters

index string | array[string] Required

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

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices.
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 or OR.

Values are and, AND, or, or OR.
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.
ignore_unavailable boolean

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

If true, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.
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.

application/json

Body

query object

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

External documentation

Responses

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

GET /{index}/_validate/query

curl \
 --request GET 'http://api.example.com/{index}/_validate/query' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"query":{}}'

Request examples

{
  "query": {}
}

Response examples (200)

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

Inference

Inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Azure, Google AI Studio or Hugging Face. For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs.

Perform chat completion inference Added in 8.18.0

POST /_inference/chat_completion/{inference_id}/_stream

Api key auth Basic auth Bearer auth

Path parameters

inference_id string Required

The inference Id

Query parameters

timeout string

Specifies the amount of time to wait for the inference request to complete.

application/json

Body Required

messages array[object] Required

A list of objects representing the conversation.
Hide messages attributes Show messages attributes object
- content string | array[object]
  
  One of:
  MessageContent string MessageContent array[object]
- role string Required
  
  The role of the message author.
- tool_call_id string
- tool_calls array[object]
  
  The tool calls generated by the model.
  Hide tool_calls attributes Show tool_calls attributes object
  
  id string Required
  
  function object Required
  
  Hide function attributes Show function attributes object
  
  arguments string Required
  
  The arguments to call the function with in JSON format.
  
  name string Required
  
  The name of the function to call.
  
  type string Required
  
  The type of the tool call.
model string

The ID of the model to use.
max_completion_tokens number

The upper bound limit for the number of tokens that can be generated for a completion request.
stop array[string]

A sequence of strings to control when the model should stop generating additional tokens.
temperature number

The sampling temperature to use.
tool_choice string | object
One of:
CompletionToolType string CompletionToolChoice object
Hide attributes Show attributes

type string Required

The type of the tool.

function object Required

Hide function attribute Show function attribute object

name string Required

The name of the function to call.
tools array[object]

A list of tools that the model can call.
Hide tools attributes Show tools attributes object
- type string Required
  
  The type of tool.
- function object Required
  Hide function attributes Show function attributes object
  
  description string
  
  A description of what the function does. This is used by the model to choose when and how to call the function.
  
  name string Required
  
  The name of the function.
  
  parameters object
  
  The parameters the functional accepts. This should be formatted as a JSON object.
  
  strict boolean
  
  Whether to enable schema adherence when generating the function call.
top_p number

Nucleus sampling, an alternative to sampling with temperature.

Responses

200 application/json

POST /_inference/chat_completion/{inference_id}/_stream

curl \
 --request POST 'http://api.example.com/_inference/chat_completion/{inference_id}/_stream' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"messages":[{"":"string","role":"string","tool_call_id":"string","tool_calls":[{"id":"string","function":{"arguments":"string","name":"string"},"type":"string"}]}],"model":"string","max_completion_tokens":42.0,"stop":["string"],"temperature":42.0,"":"string","tools":[{"type":"string","function":{"description":"string","name":"string","parameters":{},"strict":true}}],"top_p":42.0}'

Request examples

{
  "messages": [
    {
      "": "string",
      "role": "string",
      "tool_call_id": "string",
      "tool_calls": [
        {
          "id": "string",
          "function": {
            "arguments": "string",
            "name": "string"
          },
          "type": "string"
        }
      ]
    }
  ],
  "model": "string",
  "max_completion_tokens": 42.0,
  "stop": [
    "string"
  ],
  "temperature": 42.0,
  "": "string",
  "tools": [
    {
      "type": "string",
      "function": {
        "description": "string",
        "name": "string",
        "parameters": {},
        "strict": true
      }
    }
  ],
  "top_p": 42.0
}

Response examples (200)

{}

Perform completion inference on the service Added in 8.11.0

POST /_inference/completion/{inference_id}

Api key auth Basic auth Bearer auth

Path parameters

inference_id string Required

The inference Id

Query parameters

timeout string

Specifies the amount of time to wait for the inference request to complete.

application/json

Body

input string | array[string] Required

Inference input. Either a string or an array of strings.

One of:
string-1 string array-2 array[string]
task_settings object

Responses

200 application/json
Hide response attribute Show response attribute object
- completion array[object] Required
  
  Hide completion attribute Show completion attribute object
  
  result string Required

POST /_inference/completion/{inference_id}

curl \
 --request POST 'http://api.example.com/_inference/completion/{inference_id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"input\": \"What is Elastic?\"\n}"'

Request example

Run `POST _inference/completion/openai_chat_completions` to perform a completion on the example question.

{
  "input": "What is Elastic?"
}

Response examples (200)

A successful response from `POST _inference/completion/openai_chat_completions`.

{
  "completion": [
    {
      "result": "Elastic is a company that provides a range of software solutions for search, logging, security, and analytics. Their flagship product is Elasticsearch, an open-source, distributed search engine that allows users to search, analyze, and visualize large volumes of data in real-time. Elastic also offers products such as Kibana, a data visualization tool, and Logstash, a log management and pipeline tool, as well as various other tools and solutions for data analysis and management."
    }
  ]
}

Delete an inference endpoint Added in 8.11.0

DELETE /_inference/{task_type}/{inference_id}

Api key auth Basic auth Bearer auth

Path parameters

task_type string Required

The task type

Values are sparse_embedding, text_embedding, rerank, completion, or chat_completion.
inference_id string Required

The inference identifier.

Query parameters

dry_run boolean

When true, the endpoint is not deleted and a list of ingest processors which reference this endpoint is returned.
force boolean

When true, the inference endpoint is forcefully deleted even if it is still being used by ingest processors or semantic text fields.

Responses

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

DELETE /_inference/{task_type}/{inference_id}

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

Response examples (200)

{
  "acknowledged": true,
  "pipelines": [
    "string"
  ]
}

Get an inference endpoint Added in 8.11.0

GET /_inference

Api key auth Basic auth Bearer auth

Responses

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

GET /_inference

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

Response examples (200)

{
  "endpoints": [
    {
      "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"
    }
  ]
}

Create a Cohere inference endpoint Added in 8.13.0

PUT /_inference/{task_type}/{cohere_inference_id}

Api key auth Basic auth Bearer auth

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

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 completion, rerank, or text_embedding.
cohere_inference_id string Required

The unique identifier of the inference endpoint.

application/json

Body

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

Value is cohere.
service_settings object Required
Hide service_settings attributes Show service_settings attributes object
- api_key string Required
  
  A valid API key for your Cohere account. You can find or create your Cohere API keys on the Cohere API key settings page.
  
  IMPORTANT: You need to provide the API key only once, during the inference model creation. The get inference endpoint API does not retrieve your API key. After creating the inference model, you cannot change the associated API key. If you want to use a different API key, delete the inference model and recreate it with the same name and the updated API key.
  
  External documentation
- embedding_type string
  
  Values are byte, float, or int8.
- model_id string
  For a completion, rerank, or text_embedding task, the name of the model to use for the inference task.
  
  For the available completion models, refer to the Cohere command docs.
  
  For the available rerank models, refer to the Cohere rerank docs.
  
  For the available text_embedding models, refer to Cohere embed docs.
  
  The default value for a text embedding task is embed-english-v2.0.
- rate_limit object
  Hide rate_limit attribute Show rate_limit attribute object
  
  requests_per_minute number
  
  The number of requests allowed per minute.
- similarity string
  
  Values are cosine, dot_product, or l2_norm.
task_settings object
Hide task_settings attributes Show task_settings attributes object
- input_type string
  
  Values are classification, clustering, ingest, or search.
- return_documents boolean
  
  For a rerank task, return doc text within the results.
- top_n number
  
  For a rerank task, the number of most relevant documents to return. It defaults to the number of the documents. If this inference endpoint is used in a text_similarity_reranker retriever query and top_n is set, it must be greater than or equal to rank_window_size in the query.
- truncate string
  
  Values are END, NONE, or START.

Responses

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

PUT /_inference/{task_type}/{cohere_inference_id}

curl \
 --request PUT 'http://api.example.com/_inference/{task_type}/{cohere_inference_id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n    \"service\": \"cohere\",\n    \"service_settings\": {\n        \"api_key\": \"Cohere-Api-key\",\n        \"model_id\": \"embed-english-light-v3.0\",\n        \"embedding_type\": \"byte\"\n    }\n}"'

Request examples

Run `PUT _inference/text_embedding/cohere-embeddings` to create an inference endpoint that performs a text embedding task.

{
    "service": "cohere",
    "service_settings": {
        "api_key": "Cohere-Api-key",
        "model_id": "embed-english-light-v3.0",
        "embedding_type": "byte"
    }
}

Run `PUT _inference/rerank/cohere-rerank` to create an inference endpoint that performs a rerank task.

{
    "service": "cohere",
    "service_settings": {
        "api_key": "Cohere-API-key",
        "model_id": "rerank-english-v3.0"
    },
    "task_settings": {
        "top_n": 10,
        "return_documents": true
    }
}

Response examples (200)

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

Create an Elasticsearch inference endpoint Added in 8.13.0

PUT /_inference/{task_type}/{elasticsearch_inference_id}

Api key auth Basic auth Bearer auth

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

Your Elasticsearch deployment contains preconfigured ELSER and E5 inference endpoints, you only need to create the enpoints using the API if you want to customize the settings.

If you use the ELSER or the E5 model through the elasticsearch service, the API request will automatically download and deploy the model if it isn't downloaded yet.

You might see a 502 bad gateway error in the response when using the Kibana Console. This error usually just reflects a timeout, while the model downloads in the background. You can check the download progress in the Machine Learning UI. If using the Python client, you can set the timeout parameter to a higher value.

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, sparse_embedding, or text_embedding.
elasticsearch_inference_id string Required

The unique identifier of the inference endpoint. The must not match the model_id.

application/json

Body

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

Value is elasticsearch.
service_settings object Required
Hide service_settings attributes Show service_settings attributes object
- adaptive_allocations object
  Hide adaptive_allocations attributes Show adaptive_allocations attributes object
  
  enabled boolean
  
  Turn on adaptive_allocations.
  
  max_number_of_allocations number
  
  The maximum number of allocations to scale to. If set, it must be greater than or equal to min_number_of_allocations.
  
  min_number_of_allocations number
  
  The minimum number of allocations to scale to. If set, it must be greater than or equal to 0. If not defined, the deployment scales to 0.
- deployment_id string
  
  The deployment identifier for a trained model deployment. When deployment_id is used the model_id is optional.
- model_id string Required
  
  The name of the model to use for the inference task. It can be the ID of a built-in model (for example, .multilingual-e5-small for E5) or a text embedding model that was uploaded by using the Eland client.
  
  External documentation
- num_allocations number
  
  The total number of allocations that are assigned to the model across machine learning nodes. Increasing this value generally increases the throughput. If adaptive allocations are enabled, do not set this value because it's automatically set.
- num_threads number Required
  
  The number of threads used by each model allocation during inference. This setting generally increases the speed per inference request. The inference process is a compute-bound process; threads_per_allocations must not exceed the number of available allocated processors per node. The value must be a power of 2. The maximum value is 32.
task_settings object
Hide task_settings attribute Show task_settings attribute object
- return_documents boolean
  
  For a rerank task, return the document instead of only the index.

Responses

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

PUT /_inference/{task_type}/{elasticsearch_inference_id}

curl \
 --request PUT 'http://api.example.com/_inference/{task_type}/{elasticsearch_inference_id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n    \"service\": \"elasticsearch\",\n    \"service_settings\": {\n        \"adaptive_allocations\": { \n        \"enabled\": true,\n        \"min_number_of_allocations\": 1,\n        \"max_number_of_allocations\": 4\n        },\n        \"num_threads\": 1,\n        \"model_id\": \".elser_model_2\" \n    }\n}"'

Request examples

Run `PUT _inference/sparse_embedding/my-elser-model` to create an inference endpoint that performs a `sparse_embedding` task. The `model_id` must be the ID of one of the built-in ELSER models. The API will automatically download the ELSER model if it isn't already downloaded and then deploy the model.

{
    "service": "elasticsearch",
    "service_settings": {
        "adaptive_allocations": { 
        "enabled": true,
        "min_number_of_allocations": 1,
        "max_number_of_allocations": 4
        },
        "num_threads": 1,
        "model_id": ".elser_model_2" 
    }
}

Run `PUT _inference/rerank/my-elastic-rerank` to create an inference endpoint that performs a rerank task using the built-in Elastic Rerank cross-encoder model. The `model_id` must be `.rerank-v1`, which is the ID of the built-in Elastic Rerank model. The API will automatically download the Elastic Rerank model if it isn't already downloaded and then deploy the model. Once deployed, the model can be used for semantic re-ranking with a `text_similarity_reranker` retriever.

{
    "service": "elasticsearch",
    "service_settings": {
        "model_id": ".rerank-v1", 
        "num_threads": 1,
        "adaptive_allocations": { 
        "enabled": true,
        "min_number_of_allocations": 1,
        "max_number_of_allocations": 4
        }
    }
}

Run `PUT _inference/text_embedding/my-e5-model` to create an inference endpoint that performs a `text_embedding` task. The `model_id` must be the ID of one of the built-in E5 models. The API will automatically download the E5 model if it isn't already downloaded and then deploy the model.

{
    "service": "elasticsearch",
    "service_settings": {
        "num_allocations": 1,
        "num_threads": 1,
        "model_id": ".multilingual-e5-small" 
    }
}

Run `PUT _inference/text_embedding/my-msmarco-minilm-model` to create an inference endpoint that performs a `text_embedding` task with a model that was uploaded by Eland.

{
    "service": "elasticsearch",
    "service_settings": {
        "num_allocations": 1,
        "num_threads": 1,
        "model_id": "msmarco-MiniLM-L12-cos-v5" 
    }
}

Run `PUT _inference/text_embedding/my-e5-model` to create an inference endpoint that performs a `text_embedding` task and to configure adaptive allocations. The API request will automatically download the E5 model if it isn't already downloaded and then deploy the model.

{
    "service": "elasticsearch",
    "service_settings": {
        "adaptive_allocations": {
        "enabled": true,
        "min_number_of_allocations": 3,
        "max_number_of_allocations": 10
        },
        "num_threads": 1,
        "model_id": ".multilingual-e5-small"
    }
}

Run `PUT _inference/sparse_embedding/use_existing_deployment` to use an already existing model deployment when creating an inference endpoint.

{
    "service": "elasticsearch",
    "service_settings": {
        "deployment_id": ".elser_model_2"
    }
}

Response examples (200)

A successful response from `PUT _inference/sparse_embedding/use_existing_deployment`. It contains the model ID and the threads and allocations settings from the model deployment.

{
  "inference_id": "use_existing_deployment",
  "task_type": "sparse_embedding",
  "service": "elasticsearch",
  "service_settings": {
    "num_allocations": 2,
    "num_threads": 1,
    "model_id": ".elser_model_2",
    "deployment_id": ".elser_model_2"
  },
  "chunking_settings": {
    "strategy": "sentence",
    "max_chunk_size": 250,
    "sentence_overlap": 1
  }
}

Update the license

POST /_license

Api key auth Basic auth Bearer auth

You can update your license at runtime without shutting down your nodes. License updates take effect immediately. If the license you are installing does not support all of the features that were available with your previous license, however, you are notified in the response. You must then re-submit the API request with the acknowledge parameter set to true.

NOTE: If Elasticsearch security features are enabled and you are installing a gold or higher license, you must enable TLS on the transport networking layer before you install the license. If the operator privileges feature is enabled, only operator users can use this API.

Query parameters

acknowledge boolean

Specifies whether you acknowledge the license changes.
master_timeout string

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

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

application/json

Body

license object
Hide license attributes Show license attributes object
- expiry_date_in_millis number
  
  Time unit for milliseconds
- issue_date_in_millis number
  
  Time unit for milliseconds
- start_date_in_millis number
  
  Time unit for milliseconds
- issued_to string Required
- issuer string Required
- max_nodes number | string | null
  
  One of:
  number-1 number string-2 string | null
- max_resource_units number
- signature string Required
- type string Required
  
  Values are missing, trial, basic, standard, dev, silver, gold, platinum, or enterprise.
- uid string Required
licenses array[object]

A sequence of one or more JSON documents containing the license information.
Hide licenses attributes Show licenses attributes object
- expiry_date_in_millis number
  
  Time unit for milliseconds
- issue_date_in_millis number
  
  Time unit for milliseconds
- start_date_in_millis number
  
  Time unit for milliseconds
- issued_to string Required
- issuer string Required
- max_nodes number | string | null
  
  One of:
  number-1 number string-2 string | null
- max_resource_units number
- signature string Required
- type string Required
  
  Values are missing, trial, basic, standard, dev, silver, gold, platinum, or enterprise.
- uid string Required

Responses

200 application/json
Hide response attributes Show response attributes object
- acknowledge object
  
  Hide acknowledge attributes Show acknowledge attributes object
  
  license array[string] Required
  
  message string Required
- acknowledged boolean Required
- license_status string Required
  
  Values are active, valid, invalid, or expired.

POST /_license

curl \
 --request POST 'http://api.example.com/_license' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"licenses\": [\n    {\n      \"uid\":\"893361dc-9749-4997-93cb-802e3d7fa4xx\",\n      \"type\":\"basic\",\n      \"issue_date_in_millis\":1411948800000,\n      \"expiry_date_in_millis\":1914278399999,\n      \"max_nodes\":1,\n      \"issued_to\":\"issuedTo\",\n      \"issuer\":\"issuer\",\n      \"signature\":\"xx\"\n    }\n    ]\n}"'

Request example

Run `PUT _license` to update to a basic license. NOTE: These values are invalid; you must substitute the appropriate contents from your license file.

{
  "licenses": [
    {
      "uid":"893361dc-9749-4997-93cb-802e3d7fa4xx",
      "type":"basic",
      "issue_date_in_millis":1411948800000,
      "expiry_date_in_millis":1914278399999,
      "max_nodes":1,
      "issued_to":"issuedTo",
      "issuer":"issuer",
      "signature":"xx"
    }
    ]
}

Response examples (200)

If you update to a basic license and you previously had a license with more features, you receive this type of response. You must re-submit the API request and set the `acknowledge` parameter to `true`.

{
  "acknowledged": false,
  "license_status": "valid",
  "acknowledge": {
    "message": "\"\"\"This license update requires acknowledgement. To acknowledge the license, please read the following messages and update the license again, this time with the \"acknowledge=true\" parameter:\"\"\"",
    "watcher": [
      "Watcher will be disabled"
    ],
    "logstash": [
      "Logstash will no longer poll for centrally-managed pipelines"
    ],
    "security": [
      "The following X-Pack security functionality will be disabled ..."
    ]
  }
}

Create a datafeed Added in 5.4.0

PUT /_ml/datafeeds/{datafeed_id}

Api key auth Basic auth Bearer auth

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

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

Path parameters

datafeed_id string Required

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

Query parameters

allow_no_indices boolean

If true, wildcard indices expressions that resolve into no concrete indices are ignored. This includes the _all string or when no indices are specified.
expand_wildcards string | array[string]

Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values.
ignore_throttled boolean Deprecated

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

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

application/json

Body Required

aggregations object

If set, the datafeed performs aggregation searches. Support for aggregations is limited and should be used only with low cardinality data.
chunking_config object
Hide chunking_config attributes Show chunking_config attributes object
- mode string Required
  
  Values are auto, manual, or off.
- time_span string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
delayed_data_check_config object
Hide delayed_data_check_config attributes Show delayed_data_check_config attributes object
- check_window string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
- enabled boolean Required
  
  Specifies whether the datafeed periodically checks for delayed data.
frequency string

A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
indices string | array[string]
indices_options object
Hide indices_options attributes Show indices_options attributes object
- allow_no_indices boolean
  
  If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
- expand_wildcards string | array[string]
- ignore_unavailable boolean
  
  If true, missing or closed indices are not included in the response.
- ignore_throttled boolean
  
  If true, concrete, expanded or aliased indices are ignored when frozen.
job_id string
max_empty_searches number

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

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

External documentation
query_delay string

A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string ScriptSource object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
script_fields object

Specifies scripts that evaluate custom expressions and returns script fields to the datafeed. The detector configuration objects in a job can contain functions that use these script fields.
Hide script_fields attribute Show script_fields attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  script object Required
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string ScriptSource object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  ignore_failure boolean
scroll_size number

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

Responses

200 application/json
Hide response attributes Show response attributes object
- aggregations object
- authorization object
  
  Hide authorization attributes Show authorization attributes object
  
  api_key object
  
  Hide api_key attributes Show api_key attributes object
  
  id string Required
  
  The identifier for the API key.
  
  name string Required
  
  The name of the API key.
  
  roles array[string]
  
  If a user ID was used for the most recent update to the datafeed, its roles at the time of the update are listed in the response.
  
  service_account string
  
  If a service account was used for the most recent update to the datafeed, the account name is listed in the response.
- chunking_config object Required
  
  Hide chunking_config attributes Show chunking_config attributes object
  
  mode string Required
  
  Values are auto, manual, or off.
  
  time_span string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
- delayed_data_check_config object
  
  Hide delayed_data_check_config attributes Show delayed_data_check_config attributes object
  
  check_window string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  enabled boolean Required
  
  Specifies whether the datafeed periodically checks for delayed data.
- datafeed_id string Required
- frequency string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
- indices array[string] Required
- job_id string Required
- indices_options object
  
  Hide indices_options attributes Show indices_options attributes object
  
  allow_no_indices boolean
  
  If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
  
  expand_wildcards string | array[string]
  
  ignore_unavailable boolean
  
  If true, missing or closed indices are not included in the response.
  
  ignore_throttled boolean
  
  If true, concrete, expanded or aliased indices are ignored when frozen.
- max_empty_searches number
- query object Required
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
- query_delay string Required
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
- runtime_mappings object
  
  Hide runtime_mappings attribute Show runtime_mappings attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string ScriptSource object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
- script_fields object
  
  Hide script_fields attribute Show script_fields attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  script object Required
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string ScriptSource object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  ignore_failure boolean
- scroll_size number Required

PUT /_ml/datafeeds/{datafeed_id}

curl \
 --request PUT 'http://api.example.com/_ml/datafeeds/{datafeed_id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"aggregations":{},"chunking_config":{"mode":"auto","time_span":"string"},"delayed_data_check_config":{"check_window":"string","enabled":true},"frequency":"string","indices":"string","indices_options":{"allow_no_indices":true,"expand_wildcards":"string","ignore_unavailable":true,"ignore_throttled":true},"job_id":"string","max_empty_searches":42.0,"query":{},"query_delay":"string","runtime_mappings":{"additionalProperty1":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"},"additionalProperty2":{"fields":{"additionalProperty1":{"type":"boolean"},"additionalProperty2":{"type":"boolean"}},"fetch_fields":[{"field":"string","format":"string"}],"format":"string","input_field":"string","target_field":"string","target_index":"string","script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"type":"boolean"}},"script_fields":{"additionalProperty1":{"script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true},"additionalProperty2":{"script":{"":"painless","id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}},"options":{"additionalProperty1":"string","additionalProperty2":"string"}},"ignore_failure":true}},"scroll_size":42.0,"headers":{}}'

Request examples

{
  "aggregations": {},
  "chunking_config": {
    "mode": "auto",
    "time_span": "string"
  },
  "delayed_data_check_config": {
    "check_window": "string",
    "enabled": true
  },
  "frequency": "string",
  "indices": "string",
  "indices_options": {
    "allow_no_indices": true,
    "expand_wildcards": "string",
    "ignore_unavailable": true,
    "ignore_throttled": true
  },
  "job_id": "string",
  "max_empty_searches": 42.0,
  "query": {},
  "query_delay": "string",
  "runtime_mappings": {
    "additionalProperty1": {
      "fields": {
        "additionalProperty1": {
          "type": "boolean"
        },
        "additionalProperty2": {
          "type": "boolean"
        }
      },
      "fetch_fields": [
        {
          "field": "string",
          "format": "string"
        }
      ],
      "format": "string",
      "input_field": "string",
      "target_field": "string",
      "target_index": "string",
      "script": {
        "": "painless",
        "id": "string",
        "params": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "options": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        }
      },
      "type": "boolean"
    },
    "additionalProperty2": {
      "fields": {
        "additionalProperty1": {
          "type": "boolean"
        },
        "additionalProperty2": {
          "type": "boolean"
        }
      },
      "fetch_fields": [
        {
          "field": "string",
          "format": "string"
        }
      ],
      "format": "string",
      "input_field": "string",
      "target_field": "string",
      "target_index": "string",
      "script": {
        "": "painless",
        "id": "string",
        "params": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "options": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        }
      },
      "type": "boolean"
    }
  },
  "script_fields": {
    "additionalProperty1": {
      "script": {
        "": "painless",
        "id": "string",
        "params": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "options": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        }
      },
      "ignore_failure": true
    },
    "additionalProperty2": {
      "script": {
        "": "painless",
        "id": "string",
        "params": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "options": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        }
      },
      "ignore_failure": true
    }
  },
  "scroll_size": 42.0,
  "headers": {}
}

Response examples (200)

{
  "aggregations": {},
  "authorization": {
    "api_key": {
      "id": "string",
      "name": "string"
    },
    "roles": [
      "string"
    ],
    "service_account": "string"
  },
  "chunking_config": {
    "mode": "auto",
    "time_span": "string"
  },
  "delayed_data_check_config": {
    "check_window": "string",
    "enabled": true
  },
  "datafeed_id": "string",
  "frequency": "string",
  "indices": [
    "string"
  ],
  "job_id": "string",
  "indices_options": {
    "allow_no_indices": true,
    "expand_wildcards": "string",
    "ignore_unavailable": true,
    "ignore_throttled": true
  },
  "max_empty_searches": 42.0,
  "query": {},
  "query_delay": "string",
  "runtime_mappings": {
    "additionalProperty1": {
      "fields": {
        "additionalProperty1": {
          "type": "boolean"
        },
        "additionalProperty2": {
          "type": "boolean"
        }
      },
      "fetch_fields": [
        {
          "field": "string",
          "format": "string"
        }
      ],
      "format": "string",
      "input_field": "string",
      "target_field": "string",
      "target_index": "string",
      "script": {
        "": "painless",
        "id": "string",
        "params": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "options": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        }
      },
      "type": "boolean"
    },
    "additionalProperty2": {
      "fields": {
        "additionalProperty1": {
          "type": "boolean"
        },
        "additionalProperty2": {
          "type": "boolean"
        }
      },
      "fetch_fields": [
        {
          "field": "string",
          "format": "string"
        }
      ],
      "format": "string",
      "input_field": "string",
      "target_field": "string",
      "target_index": "string",
      "script": {
        "": "painless",
        "id": "string",
        "params": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "options": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        }
      },
      "type": "boolean"
    }
  },
  "script_fields": {
    "additionalProperty1": {
      "script": {
        "": "painless",
        "id": "string",
        "params": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "options": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        }
      },
      "ignore_failure": true
    },
    "additionalProperty2": {
      "script": {
        "": "painless",
        "id": "string",
        "params": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "options": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        }
      },
      "ignore_failure": true
    }
  },
  "scroll_size": 42.0
}

Delete forecasts from a job Added in 6.5.0

DELETE /_ml/anomaly_detectors/{job_id}/_forecast

Api key auth Basic auth Bearer auth

By default, forecasts are retained for 14 days. You can specify a different retention period with the expires_in parameter in the forecast jobs API. The delete forecast API enables you to delete one or more forecasts before they expire.

Path parameters

job_id string Required

Identifier for the anomaly detection job.

Query parameters

allow_no_forecasts boolean

Specifies whether an error occurs when there are no forecasts. In particular, if this parameter is set to false and there are no forecasts associated with the job, attempts to delete all forecasts return an error.
timeout string

Specifies the period of time to wait for the completion of the delete operation. When this period of time elapses, the API fails and returns an error.

Responses

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

DELETE /_ml/anomaly_detectors/{job_id}/_forecast

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

Response examples (200)

A successful response when deleting a forecast from an anomaly detection job.

{
  "acknowledged": true
}

Get calendar configuration info Added in 6.2.0

GET /_ml/calendars

Api key auth Basic auth Bearer auth

Query parameters

from number

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

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

application/json

Body

page object
Hide page attributes Show page attributes object
- from number
  
  Skips the specified number of items.
- size number
  
  Specifies the maximum number of items to obtain.

Responses

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

GET /_ml/calendars

curl \
 --request GET 'http://api.example.com/_ml/calendars' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"page":{"from":42.0,"size":42.0}}'

Request examples

{
  "page": {
    "from": 42.0,
    "size": 42.0
  }
}

Response examples (200)

{
  "calendars": [
    {
      "calendar_id": "string",
      "description": "string",
      "job_ids": [
        "string"
      ]
    }
  ],
  "count": 42.0
}

Get anomaly detection job results for influencers Added in 5.4.0

GET /_ml/anomaly_detectors/{job_id}/results/influencers

Api key auth Basic auth Bearer auth

Influencers are the entities that have contributed to, or are to blame for, the anomalies. Influencer results are available only if an influencer_field_name is specified in the job configuration.

Path parameters

job_id string Required

Identifier for the anomaly detection job.

Query parameters

desc boolean

If true, the results are sorted in descending order.
end string | number

Returns influencers with timestamps earlier than this time. The default value means it is unset and results are not limited to specific timestamps.
exclude_interim boolean

If true, the output excludes interim results. By default, interim results are included.
influencer_score number

Returns influencers with anomaly scores greater than or equal to this value.
from number

Skips the specified number of influencers.
size number

Specifies the maximum number of influencers to obtain.
sort string

Specifies the sort field for the requested influencers. By default, the influencers are sorted by the influencer_score value.
start string | number

Returns influencers with timestamps after this time. The default value means it is unset and results are not limited to specific timestamps.

application/json

Body

page object
Hide page attributes Show page attributes object
- from number
  
  Skips the specified number of items.
- size number
  
  Specifies the maximum number of items to obtain.

Responses

200 application/json
Hide response attributes Show response attributes object
- count number Required
- influencers array[object] Required
  
  Array of influencer objects
  
  Hide influencers attributes Show influencers attributes object
  
  bucket_span number
  
  Time unit for seconds
  
  influencer_score number Required
  
  A normalized score between 0-100, which is based on the probability of the influencer in this bucket aggregated across detectors. Unlike initial_influencer_score, this value is updated by a re-normalization process as new data is analyzed.
  
  influencer_field_name string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  influencer_field_value string Required
  
  The entity that influenced, contributed to, or was to blame for the anomaly.
  
  initial_influencer_score number Required
  
  A normalized score between 0-100, which is based on the probability of the influencer aggregated across detectors. This is the initial value that was calculated at the time the bucket was processed.
  
  is_interim boolean Required
  
  If true, this is an interim result. In other words, the results are calculated based on partial input data.
  
  job_id string Required
  
  probability number Required
  
  The probability that the influencer has this behavior, in the range 0 to 1. This value can be held to a high precision of over 300 decimal places, so the influencer_score is provided as a human-readable and friendly interpretation of this value.
  
  result_type string Required
  
  Internal. This value is always set to influencer.
  
  timestamp number
  
  Time unit for milliseconds
  
  foo string
  
  Additional influencer properties are added, depending on the fields being analyzed. For example, if it’s analyzing user_name as an influencer, a field user_name is added to the result document. This information enables you to filter the anomaly results more easily.

GET /_ml/anomaly_detectors/{job_id}/results/influencers

curl \
 --request GET 'http://api.example.com/_ml/anomaly_detectors/{job_id}/results/influencers' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"page":{"from":42.0,"size":42.0}}'

Request examples

{
  "page": {
    "from": 42.0,
    "size": 42.0
  }
}

Response examples (200)

{
  "count": 42.0,
  "influencers": [
    {
      "": 42.0,
      "influencer_score": 42.0,
      "influencer_field_name": "string",
      "influencer_field_value": "string",
      "initial_influencer_score": 42.0,
      "is_interim": true,
      "job_id": "string",
      "probability": 42.0,
      "result_type": "string",
      "foo": "string"
    }
  ]
}

Get anomaly detection job model snapshot upgrade usage info Added in 7.16.0

GET /_ml/anomaly_detectors/{job_id}/model_snapshots/{snapshot_id}/_upgrade/_stats

Api key auth Basic auth Bearer auth

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

allow_no_match boolean
Specifies what to do when the request:
- Contains wildcard expressions and there are no jobs that match.
- Contains the _all string or no identifiers and there are no matches.
- Contains wildcard expressions and there are only partial matches.
The default value is true, which returns an empty jobs 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.

Responses

200 application/json
Hide response attributes Show response attributes object
- count number Required
- model_snapshot_upgrades array[object] Required
  
  Hide model_snapshot_upgrades attributes Show model_snapshot_upgrades attributes object
  
  job_id string Required
  
  snapshot_id string Required
  
  state string Required
  
  Values are loading_old_state, saving_new_state, stopped, or failed.
  
  node object Required
  
  Hide node attribute Show node attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  name string
  
  ephemeral_id string Required
  
  transport_address string Required
  
  external_id string Required
  
  attributes object Required
  
  Hide attributes attribute Show attributes attribute object
  
  * string Additional properties
  
  roles array[string] Required
  
  version string Required
  
  min_index_version number Required
  
  max_index_version number Required
  
  assignment_explanation string Required

GET /_ml/anomaly_detectors/{job_id}/model_snapshots/{snapshot_id}/_upgrade/_stats

curl \
 --request GET 'http://api.example.com/_ml/anomaly_detectors/{job_id}/model_snapshots/{snapshot_id}/_upgrade/_stats' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "count": 42.0,
  "model_snapshot_upgrades": [
    {
      "job_id": "string",
      "snapshot_id": "string",
      "state": "loading_old_state",
      "node": {
        "additionalProperty1": {
          "name": "string",
          "ephemeral_id": "string",
          "transport_address": "string",
          "external_id": "string",
          "attributes": {
            "additionalProperty1": "string",
            "additionalProperty2": "string"
          },
          "roles": [
            "string"
          ],
          "version": "string",
          "min_index_version": 42.0,
          "max_index_version": 42.0
        },
        "additionalProperty2": {
          "name": "string",
          "ephemeral_id": "string",
          "transport_address": "string",
          "external_id": "string",
          "attributes": {
            "additionalProperty1": "string",
            "additionalProperty2": "string"
          },
          "roles": [
            "string"
          ],
          "version": "string",
          "min_index_version": 42.0,
          "max_index_version": 42.0
        }
      },
      "assignment_explanation": "string"
    }
  ]
}

Update a data frame analytics job Added in 7.3.0

POST /_ml/data_frame/analytics/{id}/_update

Api key auth Basic auth Bearer auth

Path parameters

id string Required

Identifier for the data frame analytics job. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start and end with alphanumeric characters.

application/json

Body Required

description string

A description of the job.
model_memory_limit string

The approximate maximum amount of memory resources that are permitted for analytical processing. If your elasticsearch.yml file contains an xpack.ml.max_model_memory_limit setting, an error occurs when you try to create data frame analytics jobs that have model_memory_limit values greater than that setting.
max_num_threads number

The maximum number of threads to be used by the analysis. Using more threads may decrease the time necessary to complete the analysis at the cost of using more CPU. Note that the process may use additional threads for operational functionality other than the analysis itself.
allow_lazy_start boolean

Specifies whether this job can start when there is insufficient machine learning node capacity for it to be immediately assigned to a node.

Responses

200 application/json
Hide response attributes Show response attributes object
- authorization object
  
  Hide authorization attributes Show authorization attributes object
  
  api_key object
  
  Hide api_key attributes Show api_key attributes object
  
  id string Required
  
  The identifier for the API key.
  
  name string Required
  
  The name of the API key.
  
  roles array[string]
  
  If a user ID was used for the most recent update to the job, its roles at the time of the update are listed in the response.
  
  service_account string
  
  If a service account was used for the most recent update to the job, the account name is listed in the response.
- allow_lazy_start boolean Required
- analysis object Required
  
  Hide analysis attributes Show analysis attributes object
  
  classification object
  
  Hide classification attributes Show classification attributes object
  
  alpha number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This parameter affects loss calculations by acting as a multiplier of the tree depth. Higher alpha values result in shallower trees and faster training times. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to zero.
  
  dependent_variable string Required
  
  Defines which field of the document is to be predicted. It must match one of the fields in the index being used to train. If this field is missing from a document, then that document will not be used for training, but a prediction with the trained model will be generated for it. It is also known as continuous target variable. For classification analysis, the data type of the field must be numeric (integer, short, long, byte), categorical (ip or keyword), or boolean. There must be no more than 30 different values in this field. For regression analysis, the data type of the field must be numeric.
  
  downsample_factor number
  
  Advanced configuration option. Controls the fraction of data that is used to compute the derivatives of the loss function for tree training. A small value results in the use of a small fraction of the data. If this value is set to be less than 1, accuracy typically improves. However, too small a value may result in poor convergence for the ensemble and so require more trees. By default, this value is calculated during hyperparameter optimization. It must be greater than zero and less than or equal to 1.
  
  early_stopping_enabled boolean
  
  Advanced configuration option. Specifies whether the training process should finish if it is not finding any better performing models. If disabled, the training process can take significantly longer and the chance of finding a better performing model is unremarkable.
  
  eta number
  
  Advanced configuration option. The shrinkage applied to the weights. Smaller values result in larger forests which have a better generalization error. However, larger forests cause slower training. By default, this value is calculated during hyperparameter optimization. It must be a value between 0.001 and 1.
  
  eta_growth_rate_per_tree number
  
  Advanced configuration option. Specifies the rate at which eta increases for each new tree that is added to the forest. For example, a rate of 1.05 increases eta by 5% for each extra tree. By default, this value is calculated during hyperparameter optimization. It must be between 0.5 and 2.
  
  feature_bag_fraction number
  
  Advanced configuration option. Defines the fraction of features that will be used when selecting a random bag for each candidate split. By default, this value is calculated during hyperparameter optimization.
  
  feature_processors array[object]
  
  Advanced configuration option. A collection of feature preprocessors that modify one or more included fields. The analysis uses the resulting one or more features instead of the original document field. However, these features are ephemeral; they are not stored in the destination index. Multiple feature_processors entries can refer to the same document fields. Automatic categorical feature encoding still occurs for the fields that are unprocessed by a custom processor or that have categorical values. Use this property only if you want to override the automatic feature encoding of the specified fields.
  
  Hide feature_processors attributes Show feature_processors attributes object
  
  frequency_encoding object
  
  multi_encoding object
  
  n_gram_encoding object
  
  one_hot_encoding object
  
  target_mean_encoding object
  
  gamma number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies a linear penalty associated with the size of individual trees in the forest. A high gamma value causes training to prefer small trees. A small gamma value results in larger individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  lambda number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies an L2 regularization term which applies to leaf weights of the individual trees in the forest. A high lambda value causes training to favor small leaf weights. This behavior makes the prediction function smoother at the expense of potentially not being able to capture relevant relationships between the features and the dependent variable. A small lambda value results in large individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  max_optimization_rounds_per_hyperparameter number
  
  Advanced configuration option. A multiplier responsible for determining the maximum number of hyperparameter optimization steps in the Bayesian optimization procedure. The maximum number of steps is determined based on the number of undefined hyperparameters times the maximum optimization rounds per hyperparameter. By default, this value is calculated during hyperparameter optimization.
  
  max_trees number
  
  Advanced configuration option. Defines the maximum number of decision trees in the forest. The maximum value is 2000. By default, this value is calculated during hyperparameter optimization.
  
  num_top_feature_importance_values number
  
  Advanced configuration option. Specifies the maximum number of feature importance values per document to return. By default, no feature importance calculation occurs.
  
  prediction_field_name string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  randomize_seed number
  
  Defines the seed for the random generator that is used to pick training data. By default, it is randomly generated. Set it to a specific value to use the same training data each time you start a job (assuming other related parameters such as source and analyzed_fields are the same).
  
  soft_tree_depth_limit number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This soft limit combines with the soft_tree_depth_tolerance to penalize trees that exceed the specified depth; the regularized loss increases quickly beyond this depth. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.
  
  soft_tree_depth_tolerance number
  
  Advanced configuration option. This option controls how quickly the regularized loss increases when the tree depth exceeds soft_tree_depth_limit. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.01.
  
  training_percent string | number
  
  One of:
  Percentage string Percentage number
  
  class_assignment_objective string
  
  num_top_classes number
  
  Defines the number of categories for which the predicted probabilities are reported. It must be non-negative or -1. If it is -1 or greater than the total number of categories, probabilities are reported for all categories; if you have a large number of categories, there could be a significant effect on the size of your destination index. NOTE: To use the AUC ROC evaluation method, num_top_classes must be set to -1 or a value greater than or equal to the total number of categories.
  
  outlier_detection object
  
  Hide outlier_detection attributes Show outlier_detection attributes object
  
  compute_feature_influence boolean
  
  Specifies whether the feature influence calculation is enabled.
  
  feature_influence_threshold number
  
  The minimum outlier score that a document needs to have in order to calculate its feature influence score. Value range: 0-1.
  
  method string
  
  The method that outlier detection uses. Available methods are lof, ldof, distance_kth_nn, distance_knn, and ensemble. The default value is ensemble, which means that outlier detection uses an ensemble of different methods and normalises and combines their individual outlier scores to obtain the overall outlier score.
  
  n_neighbors number
  
  Defines the value for how many nearest neighbors each method of outlier detection uses to calculate its outlier score. When the value is not set, different values are used for different ensemble members. This default behavior helps improve the diversity in the ensemble; only override it if you are confident that the value you choose is appropriate for the data set.
  
  outlier_fraction number
  
  The proportion of the data set that is assumed to be outlying prior to outlier detection. For example, 0.05 means it is assumed that 5% of values are real outliers and 95% are inliers.
  
  standardization_enabled boolean
  
  If true, the following operation is performed on the columns before computing outlier scores: (x_i - mean(x_i)) / sd(x_i).
  
  regression object
  
  Hide regression attributes Show regression attributes object
  
  alpha number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This parameter affects loss calculations by acting as a multiplier of the tree depth. Higher alpha values result in shallower trees and faster training times. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to zero.
  
  dependent_variable string Required
  
  Defines which field of the document is to be predicted. It must match one of the fields in the index being used to train. If this field is missing from a document, then that document will not be used for training, but a prediction with the trained model will be generated for it. It is also known as continuous target variable. For classification analysis, the data type of the field must be numeric (integer, short, long, byte), categorical (ip or keyword), or boolean. There must be no more than 30 different values in this field. For regression analysis, the data type of the field must be numeric.
  
  downsample_factor number
  
  Advanced configuration option. Controls the fraction of data that is used to compute the derivatives of the loss function for tree training. A small value results in the use of a small fraction of the data. If this value is set to be less than 1, accuracy typically improves. However, too small a value may result in poor convergence for the ensemble and so require more trees. By default, this value is calculated during hyperparameter optimization. It must be greater than zero and less than or equal to 1.
  
  early_stopping_enabled boolean
  
  Advanced configuration option. Specifies whether the training process should finish if it is not finding any better performing models. If disabled, the training process can take significantly longer and the chance of finding a better performing model is unremarkable.
  
  eta number
  
  Advanced configuration option. The shrinkage applied to the weights. Smaller values result in larger forests which have a better generalization error. However, larger forests cause slower training. By default, this value is calculated during hyperparameter optimization. It must be a value between 0.001 and 1.
  
  eta_growth_rate_per_tree number
  
  Advanced configuration option. Specifies the rate at which eta increases for each new tree that is added to the forest. For example, a rate of 1.05 increases eta by 5% for each extra tree. By default, this value is calculated during hyperparameter optimization. It must be between 0.5 and 2.
  
  feature_bag_fraction number
  
  Advanced configuration option. Defines the fraction of features that will be used when selecting a random bag for each candidate split. By default, this value is calculated during hyperparameter optimization.
  
  feature_processors array[object]
  
  Advanced configuration option. A collection of feature preprocessors that modify one or more included fields. The analysis uses the resulting one or more features instead of the original document field. However, these features are ephemeral; they are not stored in the destination index. Multiple feature_processors entries can refer to the same document fields. Automatic categorical feature encoding still occurs for the fields that are unprocessed by a custom processor or that have categorical values. Use this property only if you want to override the automatic feature encoding of the specified fields.
  
  Hide feature_processors attributes Show feature_processors attributes object
  
  frequency_encoding object
  
  multi_encoding object
  
  n_gram_encoding object
  
  one_hot_encoding object
  
  target_mean_encoding object
  
  gamma number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies a linear penalty associated with the size of individual trees in the forest. A high gamma value causes training to prefer small trees. A small gamma value results in larger individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  lambda number
  
  Advanced configuration option. Regularization parameter to prevent overfitting on the training data set. Multiplies an L2 regularization term which applies to leaf weights of the individual trees in the forest. A high lambda value causes training to favor small leaf weights. This behavior makes the prediction function smoother at the expense of potentially not being able to capture relevant relationships between the features and the dependent variable. A small lambda value results in large individual trees and slower training. By default, this value is calculated during hyperparameter optimization. It must be a nonnegative value.
  
  max_optimization_rounds_per_hyperparameter number
  
  Advanced configuration option. A multiplier responsible for determining the maximum number of hyperparameter optimization steps in the Bayesian optimization procedure. The maximum number of steps is determined based on the number of undefined hyperparameters times the maximum optimization rounds per hyperparameter. By default, this value is calculated during hyperparameter optimization.
  
  max_trees number
  
  Advanced configuration option. Defines the maximum number of decision trees in the forest. The maximum value is 2000. By default, this value is calculated during hyperparameter optimization.
  
  num_top_feature_importance_values number
  
  Advanced configuration option. Specifies the maximum number of feature importance values per document to return. By default, no feature importance calculation occurs.
  
  prediction_field_name string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  randomize_seed number
  
  Defines the seed for the random generator that is used to pick training data. By default, it is randomly generated. Set it to a specific value to use the same training data each time you start a job (assuming other related parameters such as source and analyzed_fields are the same).
  
  soft_tree_depth_limit number
  
  Advanced configuration option. Machine learning uses loss guided tree growing, which means that the decision trees grow where the regularized loss decreases most quickly. This soft limit combines with the soft_tree_depth_tolerance to penalize trees that exceed the specified depth; the regularized loss increases quickly beyond this depth. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.
  
  soft_tree_depth_tolerance number
  
  Advanced configuration option. This option controls how quickly the regularized loss increases when the tree depth exceeds soft_tree_depth_limit. By default, this value is calculated during hyperparameter optimization. It must be greater than or equal to 0.01.
  
  training_percent string | number
  
  One of:
  Percentage string Percentage number
  
  loss_function string
  
  The loss function used during regression. Available options are mse (mean squared error), msle (mean squared logarithmic error), huber (Pseudo-Huber loss).
  
  loss_function_parameter number
  
  A positive number that is used as a parameter to the loss_function.
- analyzed_fields object
  
  Hide analyzed_fields attributes Show analyzed_fields attributes object
  
  includes array[string]
  
  An array of strings that defines the fields that will be excluded from the analysis. You do not need to add fields with unsupported data types to excludes, these fields are excluded from the analysis automatically.
  
  excludes array[string]
  
  An array of strings that defines the fields that will be included in the analysis.
- create_time number Required
- description string
- dest object Required
  
  Hide dest attributes Show dest attributes object
  
  index string Required
  
  results_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- id string Required
- max_num_threads number Required
- model_memory_limit string Required
- source object Required
  
  Hide source attributes Show source attributes object
  
  index string | array[string] Required
  
  runtime_mappings object
  
  Hide runtime_mappings attribute Show runtime_mappings attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string ScriptSource object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  _source object
  
  Hide _source attributes Show _source attributes object
  
  includes array[string]
  
  An array of strings that defines the fields that will be excluded from the analysis. You do not need to add fields with unsupported data types to excludes, these fields are excluded from the analysis automatically.
  
  excludes array[string]
  
  An array of strings that defines the fields that will be included in the analysis.
  
  query object
  
  The Elasticsearch query domain-specific language (DSL). This value corresponds to the query object in an Elasticsearch search POST body. All the options that are supported by Elasticsearch can be used, as this object is passed verbatim to Elasticsearch. By default, this property has the following value: {"match_all": {}}.
  
  Query DSL
- version string Required

POST /_ml/data_frame/analytics/{id}/_update

curl \
 --request POST 'http://api.example.com/_ml/data_frame/analytics/{id}/_update' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"description":"string","model_memory_limit":"string","max_num_threads":42.0,"allow_lazy_start":true}'

Request examples

{
  "description": "string",
  "model_memory_limit": "string",
  "max_num_threads": 42.0,
  "allow_lazy_start": true
}

Response examples (200)

{
  "authorization": {
    "api_key": {
      "id": "string",
      "name": "string"
    },
    "roles": [
      "string"
    ],
    "service_account": "string"
  },
  "allow_lazy_start": true,
  "analysis": {
    "classification": {
      "alpha": 42.0,
      "dependent_variable": "string",
      "downsample_factor": 42.0,
      "early_stopping_enabled": true,
      "eta": 42.0,
      "eta_growth_rate_per_tree": 42.0,
      "feature_bag_fraction": 42.0,
      "feature_processors": [
        {
          "frequency_encoding": {},
          "multi_encoding": {},
          "n_gram_encoding": {},
          "one_hot_encoding": {},
          "target_mean_encoding": {}
        }
      ],
      "gamma": 42.0,
      "lambda": 42.0,
      "max_optimization_rounds_per_hyperparameter": 42.0,
      "max_trees": 42.0,
      "num_top_feature_importance_values": 42.0,
      "prediction_field_name": "string",
      "randomize_seed": 42.0,
      "soft_tree_depth_limit": 42.0,
      "soft_tree_depth_tolerance": 42.0,
      "": "string",
      "class_assignment_objective": "string",
      "num_top_classes": 42.0
    },
    "outlier_detection": {
      "compute_feature_influence": true,
      "feature_influence_threshold": 42.0,
      "method": "string",
      "n_neighbors": 42.0,
      "outlier_fraction": 42.0,
      "standardization_enabled": true
    },
    "regression": {
      "alpha": 42.0,
      "dependent_variable": "string",
      "downsample_factor": 42.0,
      "early_stopping_enabled": true,
      "eta": 42.0,
      "eta_growth_rate_per_tree": 42.0,
      "feature_bag_fraction": 42.0,
      "feature_processors": [
        {
          "frequency_encoding": {},
          "multi_encoding": {},
          "n_gram_encoding": {},
          "one_hot_encoding": {},
          "target_mean_encoding": {}
        }
      ],
      "gamma": 42.0,
      "lambda": 42.0,
      "max_optimization_rounds_per_hyperparameter": 42.0,
      "max_trees": 42.0,
      "num_top_feature_importance_values": 42.0,
      "prediction_field_name": "string",
      "randomize_seed": 42.0,
      "soft_tree_depth_limit": 42.0,
      "soft_tree_depth_tolerance": 42.0,
      "": "string",
      "loss_function": "string",
      "loss_function_parameter": 42.0
    }
  },
  "analyzed_fields": {
    "includes": [
      "string"
    ],
    "excludes": [
      "string"
    ]
  },
  "create_time": 42.0,
  "description": "string",
  "dest": {
    "index": "string",
    "results_field": "string"
  },
  "id": "string",
  "max_num_threads": 42.0,
  "model_memory_limit": "string",
  "source": {
    "index": "string",
    "runtime_mappings": {
      "additionalProperty1": {
        "fields": {
          "additionalProperty1": {
            "type": "boolean"
          },
          "additionalProperty2": {
            "type": "boolean"
          }
        },
        "fetch_fields": [
          {
            "field": "string",
            "format": "string"
          }
        ],
        "format": "string",
        "input_field": "string",
        "target_field": "string",
        "target_index": "string",
        "script": {
          "": "painless",
          "id": "string",
          "params": {
            "additionalProperty1": {},
            "additionalProperty2": {}
          },
          "options": {
            "additionalProperty1": "string",
            "additionalProperty2": "string"
          }
        },
        "type": "boolean"
      },
      "additionalProperty2": {
        "fields": {
          "additionalProperty1": {
            "type": "boolean"
          },
          "additionalProperty2": {
            "type": "boolean"
          }
        },
        "fetch_fields": [
          {
            "field": "string",
            "format": "string"
          }
        ],
        "format": "string",
        "input_field": "string",
        "target_field": "string",
        "target_index": "string",
        "script": {
          "": "painless",
          "id": "string",
          "params": {
            "additionalProperty1": {},
            "additionalProperty2": {}
          },
          "options": {
            "additionalProperty1": "string",
            "additionalProperty2": "string"
          }
        },
        "type": "boolean"
      }
    },
    "_source": {
      "includes": [
        "string"
      ],
      "excludes": [
        "string"
      ]
    },
    "query": {}
  },
  "version": "string"
}

Delete a trained model alias Added in 7.13.0

DELETE /_ml/trained_models/{model_id}/model_aliases/{model_alias}

Api key auth Basic auth Bearer auth

This API deletes an existing model alias that refers to a trained model. If the model alias is missing or refers to a model other than the one identified by the model_id, this API returns an error.

Path parameters

model_id string Required

The trained model ID to which the model alias refers.
model_alias string Required

The model alias to delete.

Responses

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

DELETE /_ml/trained_models/{model_id}/model_aliases/{model_alias}

curl \
 --request DELETE 'http://api.example.com/_ml/trained_models/{model_id}/model_aliases/{model_alias}' \
 --header "Authorization: $API_KEY"

Response examples (200)

A successful response when deleting a trained model alias.

{
  "acknowledged": true
}

Get the migration reindexing status Technical preview

GET /_migration/reindex/{index}/_status

Api key auth Basic auth Bearer auth

Get the status of a migration reindex attempt for a data stream or index.

Path parameters

index string | array[string] Required

The index or data stream name.

Responses

200 application/json
Hide response attributes Show response attributes object
- start_time string | number
  
  A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string representation.
  
  One of:
  DateTime string UnitMillis number
- start_time_millis number
  
  Time unit for milliseconds
- complete boolean Required
- total_indices_in_data_stream number Required
- total_indices_requiring_upgrade number Required
- successes number Required
- in_progress array[object] Required
  
  Hide in_progress attributes Show in_progress attributes object
  
  index string Required
  
  total_doc_count number Required
  
  reindexed_doc_count number Required
- pending number Required
- errors array[object] Required
  
  Hide errors attributes Show errors attributes object
  
  index string Required
  
  message string Required
- exception string

GET /_migration/reindex/{index}/_status

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

Response examples (200)

{
  "": 42.0,
  "complete": true,
  "total_indices_in_data_stream": 42.0,
  "total_indices_requiring_upgrade": 42.0,
  "successes": 42.0,
  "in_progress": [
    {
      "index": "string",
      "total_doc_count": 42.0,
      "reindexed_doc_count": 42.0
    }
  ],
  "pending": 42.0,
  "errors": [
    {
      "index": "string",
      "message": "string"
    }
  ],
  "exception": "string"
}

Get deprecation information Added in 6.1.0

GET /{index}/_migration/deprecations

Api key auth Basic auth Bearer auth

Get information about different cluster, node, and index level settings that use deprecated features that will be removed or changed in the next major version.

TIP: This APIs is designed for indirect use by the Upgrade Assistant. You are strongly recommended to use the Upgrade Assistant.

Path parameters

index string Required

Comma-separate list of data streams or indices to check. Wildcard (*) expressions are supported.

Responses

200 application/json
Hide response attributes Show response attributes object
- cluster_settings array[object] Required
  
  Cluster-level deprecation warnings.
  
  Hide cluster_settings attributes Show cluster_settings attributes object
  
  details string
  
  Optional details about the deprecation warning.
  
  level string Required
  
  Values are none, info, warning, or critical.
  
  message string Required
  
  Descriptive information about the deprecation warning.
  
  url string Required
  
  A link to the breaking change documentation, where you can find more information about this change.
  
  resolve_during_rolling_upgrade boolean Required
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
- index_settings object Required
  
  Index warnings are sectioned off per index and can be filtered using an index-pattern in the query. This section includes warnings for the backing indices of data streams specified in the request path.
  
  Hide index_settings attribute Show index_settings attribute object
  
  * array[object] Additional properties
  
  Hide * attributes Show * attributes object
  
  details string
  
  Optional details about the deprecation warning.
  
  level string Required
  
  Values are none, info, warning, or critical.
  
  message string Required
  
  Descriptive information about the deprecation warning.
  
  url string Required
  
  A link to the breaking change documentation, where you can find more information about this change.
  
  resolve_during_rolling_upgrade boolean Required
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
- data_streams object Required
  
  Hide data_streams attribute Show data_streams attribute object
  
  * array[object] Additional properties
  
  Hide * attributes Show * attributes object
  
  details string
  
  Optional details about the deprecation warning.
  
  level string Required
  
  Values are none, info, warning, or critical.
  
  message string Required
  
  Descriptive information about the deprecation warning.
  
  url string Required
  
  A link to the breaking change documentation, where you can find more information about this change.
  
  resolve_during_rolling_upgrade boolean Required
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
- node_settings array[object] Required
  
  Node-level deprecation warnings. Since only a subset of your nodes might incorporate these settings, it is important to read the details section for more information about which nodes are affected.
  
  Hide node_settings attributes Show node_settings attributes object
  
  details string
  
  Optional details about the deprecation warning.
  
  level string Required
  
  Values are none, info, warning, or critical.
  
  message string Required
  
  Descriptive information about the deprecation warning.
  
  url string Required
  
  A link to the breaking change documentation, where you can find more information about this change.
  
  resolve_during_rolling_upgrade boolean Required
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
- ml_settings array[object] Required
  
  Machine learning-related deprecation warnings.
  
  Hide ml_settings attributes Show ml_settings attributes object
  
  details string
  
  Optional details about the deprecation warning.
  
  level string Required
  
  Values are none, info, warning, or critical.
  
  message string Required
  
  Descriptive information about the deprecation warning.
  
  url string Required
  
  A link to the breaking change documentation, where you can find more information about this change.
  
  resolve_during_rolling_upgrade boolean Required
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
- templates object Required
  
  Template warnings are sectioned off per template and include deprecations for both component templates and index templates.
  
  Hide templates attribute Show templates attribute object
  
  * array[object] Additional properties
  
  Hide * attributes Show * attributes object
  
  details string
  
  Optional details about the deprecation warning.
  
  level string Required
  
  Values are none, info, warning, or critical.
  
  message string Required
  
  Descriptive information about the deprecation warning.
  
  url string Required
  
  A link to the breaking change documentation, where you can find more information about this change.
  
  resolve_during_rolling_upgrade boolean Required
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties
- ilm_policies object Required
  
  ILM policy warnings are sectioned off per policy.
  
  Hide ilm_policies attribute Show ilm_policies attribute object
  
  * array[object] Additional properties
  
  Hide * attributes Show * attributes object
  
  details string
  
  Optional details about the deprecation warning.
  
  level string Required
  
  Values are none, info, warning, or critical.
  
  message string Required
  
  Descriptive information about the deprecation warning.
  
  url string Required
  
  A link to the breaking change documentation, where you can find more information about this change.
  
  resolve_during_rolling_upgrade boolean Required
  
  _meta object
  
  Hide _meta attribute Show _meta attribute object
  
  * object Additional properties

GET /{index}/_migration/deprecations

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

Response examples (200)

An abbreviated response from `GET /_migration/deprecations`.

{
  "cluster_settings": [
    {
      "level": "critical",
      "message": "Cluster name cannot contain ':'",
      "url": "https://www.elastic.co/guide/en/elasticsearch/reference/7.0/breaking-changes-7.0.html#_literal_literal_is_no_longer_allowed_in_cluster_name",
      "details": "This cluster is named [mycompany:logging], which contains the illegal character ':'."
    }
  ],
  "node_settings": [],
  "index_settings": {
    "logs:apache": [
      {
        "level": "warning",
        "message": "Index name cannot contain ':'",
        "url": "https://www.elastic.co/guide/en/elasticsearch/reference/7.0/breaking-changes-7.0.html#_literal_literal_is_no_longer_allowed_in_index_name",
        "details": "This index is named [logs:apache], which contains the illegal character ':'."
      }
    ]
  },
  "ml_settings": []
}

Create or update a query ruleset Added in 8.10.0

PUT /_query_rules/{ruleset_id}

Api key auth Basic auth Bearer auth

There is a limit of 100 rules per ruleset. This limit can be increased by using the xpack.applications.rules.max_rules_per_ruleset cluster setting.

IMPORTANT: Due to limitations within pinned queries, you can only select documents using ids or docs, but cannot use both in single rule. It is advised to use one or the other in query rulesets, to avoid errors. Additionally, pinned queries have a maximum limit of 100 pinned hits. If multiple matching rules pin more than 100 documents, only the first 100 documents are pinned in the order they are specified in the ruleset.

External documentation

Path parameters

ruleset_id string Required

The unique identifier of the query ruleset to be created or updated.

application/json

Body Required

rules object | array[object]
One of:
QueryRule object array-2 array[object]
Hide attributes Show attributes

rule_id string Required

type string Required

Values are pinned or exclude.

criteria object | array[object] Required

The criteria that must be met for the rule to be applied. If multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.

One of:
QueryRuleCriteria object array-2 array[object]

Hide attributes Show attributes

type string Required

Values are global, exact, exact_fuzzy, fuzzy, prefix, suffix, contains, lt, lte, gt, gte, or always.

metadata string

The metadata field to match against. This metadata will be used to match against match_criteria sent in the rule. It is required for all criteria types except always.

values array[object]

The values to match against the metadata field. Only one value must match for the criteria to be met. It is required for all criteria types except always.

Hide attributes Show attributes object

type string Required

Values are global, exact, exact_fuzzy, fuzzy, prefix, suffix, contains, lt, lte, gt, gte, or always.

metadata string

The metadata field to match against. This metadata will be used to match against match_criteria sent in the rule. It is required for all criteria types except always.

values array[object]

The values to match against the metadata field. Only one value must match for the criteria to be met. It is required for all criteria types except always.

actions object Required

Hide actions attributes Show actions attributes object

ids array[string]

The unique document IDs of the documents to apply the rule to. Only one of ids or docs may be specified and at least one must be specified.

docs array[object]

The documents to apply the rule to. Only one of ids or docs may be specified and at least one must be specified. There is a maximum value of 100 documents in a rule. You can specify the following attributes for each document:

_index: The index of the document to pin.

_id: The unique document ID.

Hide docs attributes Show docs attributes object

_id string Required

_index string

priority number
Hide attributes Show attributes object

rule_id string Required

type string Required

Values are pinned or exclude.

criteria object | array[object]

The criteria that must be met for the rule to be applied. If multiple criteria are specified for a rule, all criteria must be met for the rule to be applied.

One of:
QueryRuleCriteria object array-2 array[object]

Hide attributes Show attributes

type string Required

Values are global, exact, exact_fuzzy, fuzzy, prefix, suffix, contains, lt, lte, gt, gte, or always.

metadata string

The metadata field to match against. This metadata will be used to match against match_criteria sent in the rule. It is required for all criteria types except always.

values array[object]

The values to match against the metadata field. Only one value must match for the criteria to be met. It is required for all criteria types except always.

Hide attributes Show attributes object

type string Required

Values are global, exact, exact_fuzzy, fuzzy, prefix, suffix, contains, lt, lte, gt, gte, or always.

metadata string

The metadata field to match against. This metadata will be used to match against match_criteria sent in the rule. It is required for all criteria types except always.

values array[object]

The values to match against the metadata field. Only one value must match for the criteria to be met. It is required for all criteria types except always.

actions object Required

Hide actions attributes Show actions attributes object

ids array[string]

The unique document IDs of the documents to apply the rule to. Only one of ids or docs may be specified and at least one must be specified.

docs array[object]

The documents to apply the rule to. Only one of ids or docs may be specified and at least one must be specified. There is a maximum value of 100 documents in a rule. You can specify the following attributes for each document:

_index: The index of the document to pin.

_id: The unique document ID.

Hide docs attributes Show docs attributes object

_id string Required

_index string

priority number

Responses

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

PUT /_query_rules/{ruleset_id}

curl \
 --request PUT 'http://api.example.com/_query_rules/{ruleset_id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n    \"rules\": [\n        {\n            \"rule_id\": \"my-rule1\",\n            \"type\": \"pinned\",\n            \"criteria\": [\n                {\n                    \"type\": \"contains\",\n                    \"metadata\": \"user_query\",\n                    \"values\": [ \"pugs\", \"puggles\" ]\n                },\n                {\n                    \"type\": \"exact\",\n                    \"metadata\": \"user_country\",\n                    \"values\": [ \"us\" ]\n                }\n            ],\n            \"actions\": {\n                \"ids\": [\n                    \"id1\",\n                    \"id2\"\n                ]\n            }\n        },\n        {\n            \"rule_id\": \"my-rule2\",\n            \"type\": \"pinned\",\n            \"criteria\": [\n                {\n                    \"type\": \"fuzzy\",\n                    \"metadata\": \"user_query\",\n                    \"values\": [ \"rescue dogs\" ]\n                }\n            ],\n            \"actions\": {\n                \"docs\": [\n                    {\n                        \"_index\": \"index1\",\n                        \"_id\": \"id3\"\n                    },\n                    {\n                        \"_index\": \"index2\",\n                        \"_id\": \"id4\"\n                    }\n                ]\n            }\n        }\n    ]\n}"'

Request example

Run `PUT _query_rules/my-ruleset` to create a new query ruleset. Two rules are associated with `my-ruleset`. `my-rule1` will pin documents with IDs `id1` and `id2` when `user_query` contains `pugs` or `puggles` and `user_country` exactly matches `us`. `my-rule2` will exclude documents from different specified indices with IDs `id3` and `id4` when the `query_string` fuzzily matches `rescue dogs`.

{
    "rules": [
        {
            "rule_id": "my-rule1",
            "type": "pinned",
            "criteria": [
                {
                    "type": "contains",
                    "metadata": "user_query",
                    "values": [ "pugs", "puggles" ]
                },
                {
                    "type": "exact",
                    "metadata": "user_country",
                    "values": [ "us" ]
                }
            ],
            "actions": {
                "ids": [
                    "id1",
                    "id2"
                ]
            }
        },
        {
            "rule_id": "my-rule2",
            "type": "pinned",
            "criteria": [
                {
                    "type": "fuzzy",
                    "metadata": "user_query",
                    "values": [ "rescue dogs" ]
                }
            ],
            "actions": {
                "docs": [
                    {
                        "_index": "index1",
                        "_id": "id3"
                    },
                    {
                        "_index": "index2",
                        "_id": "id4"
                    }
                ]
            }
        }
    ]
}

Response examples (200)

{
  "result": "created"
}

Get a script or search template

GET /_scripts/{id}

Api key auth Basic auth Bearer auth

Retrieves a stored script or search template.

Path parameters

id string Required

The identifier for the stored script or search template.

Query parameters

master_timeout string

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

Responses

200 application/json
Hide response attributes Show response attributes object
- _id string Required
- found boolean Required
- script object
  
  Hide script attributes Show script attributes object
  
  lang string Required
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  source string | object Required
  
  One of:
  ScriptSource string ScriptSource object

GET /_scripts/{id}

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

Response examples (200)

{
  "_id": "string",
  "found": true,
  "script": {
    "": "string",
    "options": {
      "additionalProperty1": "string",
      "additionalProperty2": "string"
    }
  }
}

Create or update a script or search template

POST /_scripts/{id}

Api key auth Basic auth Bearer auth

Creates or updates a stored script or search template.

External documentation

Path parameters

id string Required

The identifier for the stored script or search template. It must be unique within the cluster.

Query parameters

context string

The context in which the script or search template should run. To prevent errors, the API immediately compiles the script or template in this context. If you specify both this and the <context> path parameter, the API uses the request path parameter.
master_timeout string

The 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. It can also be set to -1 to indicate that the request should never timeout.
timeout string

The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. It can also be set to -1 to indicate that the request should never timeout.

application/json

Body Required

script object Required
Hide script attributes Show script attributes object
- lang string Required
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
- options object
  Hide options attribute Show options attribute object
  
  * string Additional properties
- source string | object Required
  
  One of:
  ScriptSource string ScriptSource object

Responses

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

POST /_scripts/{id}

curl \
 --request POST 'http://api.example.com/_scripts/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"script\": {\n    \"lang\": \"mustache\",\n    \"source\": {\n      \"query\": {\n        \"match\": {\n          \"message\": \"{{query_string}}\"\n        }\n      },\n      \"from\": \"{{from}}\",\n      \"size\": \"{{size}}\"\n    }\n  }\n}"'

Request examples

Run `PUT _scripts/my-search-template` to create a search template.

{
  "script": {
    "lang": "mustache",
    "source": {
      "query": {
        "match": {
          "message": "{{query_string}}"
        }
      },
      "from": "{{from}}",
      "size": "{{size}}"
    }
  }
}

Run `PUT _scripts/my-stored-script` to create a stored script.

{
  "script": {
    "lang": "painless",
    "source": "Math.log(_score * 2) + params['my_modifier']"
  }
}

Response examples (200)

{
  "acknowledged": true
}

Clear a scrolling search

DELETE /_search/scroll/{scroll_id}

Api key auth Basic auth Bearer auth

Clear the search context and results for a scrolling search.

External documentation

Path parameters

scroll_id string | array[string] Required Deprecated

A comma-separated list of scroll IDs to clear. To clear all scroll IDs, use _all. IMPORTANT: Scroll IDs can be long. It is recommended to specify scroll IDs in the request body parameter.

application/json

Body

scroll_id string | array[string]

One of:
ScrollId string ScrollIds array[string]

Responses

200 application/json
Hide response attributes Show response attributes object
- succeeded boolean Required
  
  If true, the request succeeded. This does not indicate whether any scrolling search requests were cleared.
- num_freed number Required
  
  The number of scrolling search requests cleared.

DELETE /_search/scroll/{scroll_id}

curl \
 --request DELETE 'http://api.example.com/_search/scroll/{scroll_id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"scroll_id\": \"DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==\"\n}"'

Request example

Run `DELETE /_search/scroll` to clear the search context and results for a scrolling search.

{
  "scroll_id": "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ=="
}

Response examples (200)

{
  "succeeded": true,
  "num_freed": 42.0
}

Count search results

GET /_count

Api key auth Basic auth Bearer auth

Get the number of documents matching a query.

The query can be provided either by using a simple query string as a parameter, or by defining Query DSL within the request body. The query is optional. When no query is provided, the API uses match_all to count all the documents.

The count API supports multi-target syntax. You can run a single count API search across multiple data streams and indices.

The operation is broadcast across all shards. For each shard ID group, a replica is chosen and the search is run against it. This means that replicas increase the scalability of the count.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
analyzer string

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

If true, wildcard and prefix queries are analyzed. This parameter can be used only when the q query string parameter is specified.
default_operator string

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

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

The field to use as a default when no field prefix is given in the query string. This parameter can be used only when the q query string parameter is specified.
expand_wildcards string | array[string]

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

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

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

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

The minimum _score value that documents must have to be included in the result.
preference string

The node or shard the operation should be performed on. By default, it is random.
routing string

A custom value used to route operations to a specific shard.
terminate_after number

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

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

The query in Lucene query string syntax. This parameter cannot be used with a request body.

application/json

Body

query object

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

External documentation

Responses

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

GET /_count

curl \
 --request GET 'http://api.example.com/_count' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"query\" : {\n    \"term\" : { \"user.id\" : \"kimchy\" }\n  }\n}"'

Request example

Run `GET /my-index-000001/_count?q=user:kimchy`. Alternatively, run `GET /my-index-000001/_count` with the same query in the request body. Both requests count the number of documents in `my-index-000001` with a `user.id` of `kimchy`.

{
  "query" : {
    "term" : { "user.id" : "kimchy" }
  }
}

Response examples (200)

A successful response from `GET /my-index-000001/_count?q=user:kimchy`.

{
  "count": 1,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  }
}

Get the field capabilities Added in 5.4.0

POST /{index}/_field_caps

Api key auth Basic auth Bearer auth

Get information about the capabilities of fields among multiple indices.

For data streams, the API returns field capabilities among the stream’s backing indices. It returns runtime fields like any other field. For example, a runtime field with a type of keyword is returned the same as any other field that belongs to the keyword family.

Path parameters

index string | array[string] Required

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

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
expand_wildcards string | array[string]

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. Supports comma-separated values, such as open,hidden.
fields string | array[string]

A comma-separated list of fields to retrieve capabilities for. Wildcard (*) expressions are supported.
ignore_unavailable boolean

If true, missing or closed indices are not included in the response.
include_unmapped boolean

If true, unmapped fields are included in the response.
filters string

A comma-separated list of filters to apply to the response.
types array[string]

A comma-separated list of field types to include. Any fields that do not match one of these types will be excluded from the results. It defaults to empty, meaning that all field types are returned.
include_empty_fields boolean

If false, empty fields are not included in the response.

application/json

Body

fields string | array[string]
index_filter object

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

External documentation
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string ScriptSource object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.

Responses

200 application/json
Hide response attributes Show response attributes object
- indices string | array[string] Required
- fields object Required
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  aggregatable boolean Required
  
  Whether this field can be aggregated on all indices.
  
  indices string | array[string]
  
  meta object
  
  Hide meta attribute Show meta attribute object
  
  * object Additional properties
  
  non_aggregatable_indices string | array[string]
  
  non_searchable_indices string | array[string]
  
  searchable boolean Required
  
  Whether this field is indexed for search on all indices.
  
  type string Required
  
  metadata_field boolean
  
  Whether this field is registered as a metadata field.
  
  time_series_dimension boolean Technical preview
  
  Whether this field is used as a time series dimension.
  
  time_series_metric string
  
  Values are gauge, counter, summary, histogram, or position.
  
  non_dimension_indices array[string] Technical preview
  
  If this list is present in response then some indices have the field marked as a dimension and other indices, the ones in this list, do not.
  
  metric_conflicts_indices array[string] Technical preview
  
  The list of indices where this field is present if these indices don’t have the same time_series_metric value for this field.

POST /{index}/_field_caps

curl \
 --request POST 'http://api.example.com/{index}/_field_caps' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"index_filter\": {\n    \"range\": {\n      \"@timestamp\": {\n        \"gte\": \"2018\"\n      }\n    }\n  }\n}"'

Request example

Run `POST my-index-*/_field_caps?fields=rating` to get field capabilities and filter indices with a query. Indices that rewrite the provided filter to `match_none` on every shard will be filtered from the response.

{
  "index_filter": {
    "range": {
      "@timestamp": {
        "gte": "2018"
      }
    }
  }
}

Response examples (200)

A successful response from `GET _field_caps?fields=rating,title`. The field `rating` is defined as a long in `index1` and `index2` and as a `keyword` in `index3` and `index4`. The field `rating` is not aggregatable in `index1`. The field `rating` is not searchable in `index4`. The field `title` is defined as text in all indices.

{
  "indices": [ "index1", "index2", "index3", "index4", "index5" ],
  "fields": {
    "rating": {                                   
      "long": {
        "metadata_field": false,
        "searchable": true,
        "aggregatable": false,
        "indices": [ "index1", "index2" ],
        "non_aggregatable_indices": [ "index1" ]  
      },
      "keyword": {
        "metadata_field": false,
        "searchable": false,
        "aggregatable": true,
        "indices": [ "index3", "index4" ],
        "non_searchable_indices": [ "index4" ]    
      }
    },
    "title": {                                    
      "text": {
        "metadata_field": false,
        "searchable": true,
        "aggregatable": false
      }
    }
  }
}

A successful response from `GET _field_caps?fields=rating,title&include_unmapped`. The response contains an entry for each field that is present in some indices but not all. For example, the `rating` and `title` fields are unmapped in `index5`.

{
  "indices": [ "index1", "index2", "index3", "index4", "index5" ],
  "fields": {
    "rating": {                                   
      "long": {
        "metadata_field": false,
        "searchable": true,
        "aggregatable": false,
        "indices": [ "index1", "index2" ],
        "non_aggregatable_indices": [ "index1" ]  
      },
      "keyword": {
        "metadata_field": false,
        "searchable": false,
        "aggregatable": true,
        "indices": [ "index3", "index4" ],
        "non_searchable_indices": [ "index4" ]    
      }
    },
    "title": {                                    
      "text": {
        "metadata_field": false,
        "searchable": true,
        "aggregatable": false
      }
    }
  }
}

Run multiple templated searches Added in 5.0.0

POST /{index}/_msearch/template

Api key auth Basic auth Bearer auth

Run multiple templated searches with a single request. If you are providing a text file or text input to curl, use the --data-binary flag instead of -d to preserve newlines. For example:

$ cat requests
{ "index": "my-index" }
{ "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 }}
{ "index": "my-other-index" }
{ "id": "my-other-search-template", "params": { "query_type": "match_all" }}

$ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch/template --data-binary "@requests"; echo

External documentation

Path parameters

index string | array[string] Required

A comma-separated list of data streams, indices, and aliases to search. It supports wildcards (*). To search all data streams and indices, omit this parameter or use *.

Query parameters

ccs_minimize_roundtrips boolean

If true, network round-trips are minimized for cross-cluster search requests.
max_concurrent_searches number

The maximum number of concurrent searches the API can run.
search_type string

The type of the search operation.

Values are query_then_fetch or dfs_query_then_fetch.
rest_total_hits_as_int boolean

If true, the response returns hits.total as an integer. If false, it returns hits.total as an object.
typed_keys boolean

If true, the response prefixes aggregation and suggester names with their respective types.

application/json

Body object Required

allow_no_indices boolean
expand_wildcards string | array[string]
ignore_unavailable boolean
index string | array[string]
preference string
request_cache boolean
routing string
search_type string

Values are query_then_fetch or dfs_query_then_fetch.
ccs_minimize_roundtrips boolean
allow_partial_search_results boolean
ignore_throttled boolean

explain boolean

If true, returns detailed information about score calculation as part of each hit.
id string
params object

Key-value pairs used to replace Mustache variables in the template. The key is the variable name. The value is the variable value.
Hide params attribute Show params attribute object
- * object Additional properties
profile boolean

If true, the query execution is profiled.
source string | object

One of:
ScriptSource string ScriptSource object

Responses

200 application/json
Hide response attributes Show response attributes object
- took number Required
- responses array[object] Required
  
  One of:
  MultiSearchItem object ErrorResponseBase object
  
  Hide attributes Show attributes
  
  took number Required
  
  The number of milliseconds it took Elasticsearch to run the request. This value is calculated by measuring the time elapsed between receipt of a request on the coordinating node and the time at which the coordinating node is ready to send the response. It includes:
  
  Communication time between the coordinating node and data nodes
  
  Time the request spends in the search thread pool, queued for execution
  
  Actual run time
  
  It does not include:
  
  Time needed to send the request to Elasticsearch
  
  Time needed to serialize the JSON response
  
  Time needed to send the response to a client
  
  timed_out boolean Required
  
  If true, the request timed out before completion; returned results may be partial or empty.
  
  _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  skipped number
  
  hits object Required
  
  Hide hits attributes Show hits attributes object
  
  total
  
  hits array[object] Required
  
  max_score
  
  aggregations object
  
  _clusters object
  
  Hide _clusters attributes Show _clusters attributes object
  
  skipped number Required
  
  successful number Required
  
  total number Required
  
  running number Required
  
  partial number Required
  
  failed number Required
  
  details object
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  max_score number
  
  num_reduce_phases number
  
  profile object
  
  Hide profile attribute Show profile attribute object
  
  shards array[object] Required
  
  pit_id string
  
  _scroll_id string
  
  suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  * array[object] Additional properties
  
  terminated_early boolean
  
  status number
  
  Hide attributes Show attributes
  
  error object Required
  
  Hide error attributes Show error attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  status number Required

POST /{index}/_msearch/template

curl \
 --request POST 'http://api.example.com/{index}/_msearch/template' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{ }\n{ \"id\": \"my-search-template\", \"params\": { \"query_string\": \"hello world\", \"from\": 0, \"size\": 10 }}\n{ }\n{ \"id\": \"my-other-search-template\", \"params\": { \"query_type\": \"match_all\" }}"'

Request example

Run `GET my-index/_msearch/template` to run multiple templated searches.

{ }
{ "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 }}
{ }
{ "id": "my-other-search-template", "params": { "query_type": "match_all" }}

Response examples (200)

{
  "took": 42.0,
  "responses": [
    {
      "took": 42.0,
      "timed_out": true,
      "_shards": {
        "failed": 42.0,
        "successful": 42.0,
        "total": 42.0,
        "failures": [
          {}
        ],
        "skipped": 42.0
      },
      "hits": {
        "hits": [
          {}
        ]
      },
      "aggregations": {},
      "_clusters": {
        "skipped": 42.0,
        "successful": 42.0,
        "total": 42.0,
        "running": 42.0,
        "partial": 42.0,
        "failed": 42.0,
        "details": {}
      },
      "fields": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      },
      "max_score": 42.0,
      "num_reduce_phases": 42.0,
      "profile": {
        "shards": [
          {}
        ]
      },
      "pit_id": "string",
      "_scroll_id": "string",
      "suggest": {
        "additionalProperty1": [
          {}
        ],
        "additionalProperty2": [
          {}
        ]
      },
      "terminated_early": true,
      "status": 42.0
    }
  ]
}

Evaluate ranked search results Added in 6.2.0

GET /_rank_eval

Api key auth Basic auth Bearer auth

Evaluate the quality of ranked search results over a set of typical search queries.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
expand_wildcards string | array[string]

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

If true, missing or closed indices are not included in the response.
search_type string

Search operation type

application/json

Body Required

requests array[object] Required

A set of typical search requests, together with their provided ratings.
Hide requests attributes Show requests attributes object
- id string Required
- request object
  Hide request attributes Show request attributes object
  
  query object Required
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  size number
- ratings array[object] Required
  
  List of document ratings
  Hide ratings attributes Show ratings attributes object
  
  _id string Required
  
  _index string Required
  
  rating number Required
  
  The document’s relevance with regard to this search request.
- template_id string
- params object
  
  The search template parameters.
  Hide params attribute Show params attribute object
  
  * object Additional properties
metric object
Hide metric attributes Show metric attributes object
- precision object
  Hide precision attributes Show precision attributes object
  
  k number
  
  Sets the maximum number of documents retrieved per query. This value will act in place of the usual size parameter in the query.
  
  relevant_rating_threshold number
  
  Sets the rating threshold above which documents are considered to be "relevant".
  
  ignore_unlabeled boolean
  
  Controls how unlabeled documents in the search results are counted. If set to true, unlabeled documents are ignored and neither count as relevant or irrelevant. Set to false (the default), they are treated as irrelevant.
- recall object
  Hide recall attributes Show recall attributes object
  
  k number
  
  Sets the maximum number of documents retrieved per query. This value will act in place of the usual size parameter in the query.
  
  relevant_rating_threshold number
  
  Sets the rating threshold above which documents are considered to be "relevant".
- mean_reciprocal_rank object
  Hide mean_reciprocal_rank attributes Show mean_reciprocal_rank attributes object
  
  k number
  
  Sets the maximum number of documents retrieved per query. This value will act in place of the usual size parameter in the query.
  
  relevant_rating_threshold number
  
  Sets the rating threshold above which documents are considered to be "relevant".
- dcg object
  Hide dcg attributes Show dcg attributes object
  
  k number
  
  Sets the maximum number of documents retrieved per query. This value will act in place of the usual size parameter in the query.
  
  normalize boolean
  
  If set to true, this metric will calculate the Normalized DCG.
- expected_reciprocal_rank object
  Hide expected_reciprocal_rank attributes Show expected_reciprocal_rank attributes object
  
  k number
  
  Sets the maximum number of documents retrieved per query. This value will act in place of the usual size parameter in the query.
  
  maximum_relevance number Required
  
  The highest relevance grade used in the user-supplied relevance judgments.

Responses

200 application/json
Hide response attributes Show response attributes object
- metric_score number Required
  
  The overall evaluation quality calculated by the defined metric
- details object Required
  
  The details section contains one entry for every query in the original requests section, keyed by the search request id
  
  Hide details attribute Show details attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  metric_score number Required
  
  The metric_score in the details section shows the contribution of this query to the global quality metric score
  
  unrated_docs array[object] Required
  
  The unrated_docs section contains an _index and _id entry for each document in the search result for this query that didn’t have a ratings value. This can be used to ask the user to supply ratings for these documents
  
  Hide unrated_docs attributes Show unrated_docs attributes object
  
  _id string Required
  
  _index string Required
  
  hits array[object] Required
  
  The hits section shows a grouping of the search results with their supplied ratings
  
  Hide hits attributes Show hits attributes object
  
  hit object Required
  
  Hide hit attributes Show hit attributes object
  
  _id string Required
  
  _index string Required
  
  _score number Required
  
  rating number | string | null
  
  One of:
  number-1 number string-2 string | null
  
  metric_details object Required
  
  The metric_details give additional information about the calculated quality metric (e.g. how many of the retrieved documents were relevant). The content varies for each metric but allows for better interpretation of the results
  
  Hide metric_details attribute Show metric_details attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  * object Additional properties
- failures object Required
  
  Hide failures attribute Show failures attribute object
  
  * object Additional properties

GET /_rank_eval

curl \
 --request GET 'http://api.example.com/_rank_eval' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"requests":[{"id":"string","request":{"query":{},"size":42.0},"ratings":[{"_id":"string","_index":"string","rating":42.0}],"template_id":"string","params":{"additionalProperty1":{},"additionalProperty2":{}}}],"metric":{"precision":{"k":42.0,"relevant_rating_threshold":42.0,"ignore_unlabeled":true},"recall":{"k":42.0,"relevant_rating_threshold":42.0},"mean_reciprocal_rank":{"k":42.0,"relevant_rating_threshold":42.0},"dcg":{"k":42.0,"normalize":true},"expected_reciprocal_rank":{"k":42.0,"maximum_relevance":42.0}}}'

Request examples

{
  "requests": [
    {
      "id": "string",
      "request": {
        "query": {},
        "size": 42.0
      },
      "ratings": [
        {
          "_id": "string",
          "_index": "string",
          "rating": 42.0
        }
      ],
      "template_id": "string",
      "params": {
        "additionalProperty1": {},
        "additionalProperty2": {}
      }
    }
  ],
  "metric": {
    "precision": {
      "k": 42.0,
      "relevant_rating_threshold": 42.0,
      "ignore_unlabeled": true
    },
    "recall": {
      "k": 42.0,
      "relevant_rating_threshold": 42.0
    },
    "mean_reciprocal_rank": {
      "k": 42.0,
      "relevant_rating_threshold": 42.0
    },
    "dcg": {
      "k": 42.0,
      "normalize": true
    },
    "expected_reciprocal_rank": {
      "k": 42.0,
      "maximum_relevance": 42.0
    }
  }
}

Response examples (200)

{
  "metric_score": 42.0,
  "details": {
    "additionalProperty1": {
      "metric_score": 42.0,
      "unrated_docs": [
        {
          "_id": "string",
          "_index": "string"
        }
      ],
      "hits": [
        {
          "hit": {
            "_id": "string",
            "_index": "string",
            "_score": 42.0
          },
          "rating": 42.0
        }
      ],
      "metric_details": {
        "additionalProperty1": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "additionalProperty2": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        }
      }
    },
    "additionalProperty2": {
      "metric_score": 42.0,
      "unrated_docs": [
        {
          "_id": "string",
          "_index": "string"
        }
      ],
      "hits": [
        {
          "hit": {
            "_id": "string",
            "_index": "string",
            "_score": 42.0
          },
          "rating": 42.0
        }
      ],
      "metric_details": {
        "additionalProperty1": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        },
        "additionalProperty2": {
          "additionalProperty1": {},
          "additionalProperty2": {}
        }
      }
    }
  },
  "failures": {
    "additionalProperty1": {},
    "additionalProperty2": {}
  }
}

Render a search template

POST /_render/template/{id}

Api key auth Basic auth Bearer auth

Render a search template as a search request body.

Path parameters

id string Required

The ID of the search template to render. If no source is specified, this or the id request body parameter is required.

application/json

Body

id string
file string
params object

Key-value pairs used to replace Mustache variables in the template. The key is the variable name. The value is the variable value.
Hide params attribute Show params attribute object
- * object Additional properties
source string | object

One of:
ScriptSource string ScriptSource object

Responses

200 application/json
Hide response attribute Show response attribute object
- template_output object Required
  
  Hide template_output attribute Show template_output attribute object
  
  * object Additional properties

POST /_render/template/{id}

curl \
 --request POST 'http://api.example.com/_render/template/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"id\": \"my-search-template\",\n  \"params\": {\n    \"query_string\": \"hello world\",\n    \"from\": 20,\n    \"size\": 10\n  }\n}"'

Request example

Run `POST _render/template`

{
  "id": "my-search-template",
  "params": {
    "query_string": "hello world",
    "from": 20,
    "size": 10
  }
}

Response examples (200)

{
  "template_output": {
    "additionalProperty1": {},
    "additionalProperty2": {}
  }
}

Run a search

GET /{index}/_search

Api key auth Basic auth Bearer auth

Get search hits that match the query defined in the request. You can provide search queries using the q query string parameter or the request body. If both are specified, only the query parameter is used.

If the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges. To search a point in time (PIT) for an alias, you must have the read index privilege for the alias's data streams or indices.

Search slicing

When paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the slice and pit properties. By default the splitting is done first on the shards, then locally on each shard. The local splitting partitions the shard into contiguous ranges based on Lucene document IDs.

For instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.

IMPORTANT: The same point-in-time ID should be used for all slices. If different PIT IDs are used, slices can overlap and miss documents. This situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.

External documentation

Path parameters

index string | array[string] Required

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

If true and there are shard request timeouts or shard failures, the request returns partial results. If false, it returns an error with no partial results.

To override the default behavior, you can set the search.default_allow_partial_results cluster setting to false.
analyzer string

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

If true, wildcard and prefix queries are analyzed. This parameter can be used only when the q query string parameter is specified.
batched_reduce_size number

The number of shard results that should be reduced at once on the coordinating node. If the potential number of shards in the request can be large, this value should be used as a protection mechanism to reduce the memory overhead per search request.
ccs_minimize_roundtrips boolean

If true, network round-trips between the coordinating node and the remote clusters are minimized when running cross-cluster search (CCS) requests.
default_operator string

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

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

The field to use as a default when no field prefix is given in the query string. This parameter can be used only when the q query string parameter is specified.
docvalue_fields string | array[string]

A comma-separated list of fields to return as the docvalue representation of a field for each hit.
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.
explain boolean

If true, the request returns detailed information about score computation as part of a hit.
ignore_throttled boolean Deprecated

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

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

If true, the response includes the score contribution from any named queries.

This functionality reruns each named query on every hit in a search response. Typically, this adds a small overhead to a request. However, using computationally expensive named queries on a large number of hits may add significant overhead.
lenient boolean

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

The number of concurrent shard requests per node that the search runs concurrently. This value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests.
preference string
The nodes and shards used for the search. By default, Elasticsearch selects from eligible nodes and shards using adaptive replica selection, accounting for allocation awareness. Valid values are:
- _only_local to run the search only on shards on the local node.
- _local to, if possible, run the search on shards on the local node, or if not, select shards using the default method.
- _only_nodes:<node-id>,<node-id> to run the search on only the specified nodes IDs. If suitable shards exist on more than one selected node, use shards on those nodes using the default method. If none of the specified nodes are available, select shards from any available node using the default method.
- _prefer_nodes:<node-id>,<node-id> to if possible, run the search on the specified nodes IDs. If not, select shards using the default method. _shards:<shard>,<shard> to run the search only on the specified shards. You can combine this value with other preference values. However, the _shards value must come first. For example: _shards:2,3|_local. <custom-string> (any string that does not start with _) to route searches with the same <custom-string> to the same shards in the same order.
pre_filter_shard_size number
A threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method (if date filters are mandatory to match but the shard bounds and the query are disjoint). When unspecified, the pre-filter phase is executed if any of these conditions is met:
- The request targets more than 128 shards.
- The request targets one or more read-only index.
- The primary sort of the query targets an indexed field.
request_cache boolean

If true, the caching of search results is enabled for requests where size is 0. It defaults to index level settings.
routing string

A custom value that is used to route operations to a specific shard.
scroll string

The period to retain the search context for scrolling. By default, this value cannot exceed 1d (24 hours). You can change this limit by using the search.max_keep_alive cluster-level setting.
search_type string

Indicates how distributed term frequencies are calculated for relevance scoring.

Values are query_then_fetch or dfs_query_then_fetch.
stats array[string]

Specific tag of the request for logging and statistical purposes.
stored_fields string | array[string]

A comma-separated list of stored fields to return as part of a hit. If no fields are specified, no stored fields are included in the response. If this field is specified, the _source parameter defaults to false. You can pass _source: true to return both source fields and stored fields in the search response.
suggest_field string

The field to use for suggestions.
suggest_mode string

The suggest mode. This parameter can be used only when the suggest_field and suggest_text query string parameters are specified.

Values are missing, popular, or always.
suggest_size number

The number of suggestions to return. This parameter can be used only when the suggest_field and suggest_text query string parameters are specified.
suggest_text string

The source text for which the suggestions should be returned. This parameter can be used only when the suggest_field and suggest_text query string parameters are specified.
terminate_after number

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

IMPORTANT: Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers. If set to 0 (default), the query does not terminate early.
timeout string

The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. It defaults to no timeout.
track_total_hits boolean | number

The number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query.
track_scores boolean

If true, the request calculates and returns document scores, even if the scores are not used for sorting.
typed_keys boolean

If true, aggregation and suggester names are be prefixed by their respective types in the response.
rest_total_hits_as_int boolean

Indicates whether hits.total should be rendered as an integer or an object in the rest search response.
version boolean

If true, the request returns the document version as part of a hit.
_source boolean | string | array[string]
The source fields that are returned for matching documents. These fields are returned in the hits._source property of the search response. Valid values are:
- true to return the entire document source.
- false to not return the document source.
- <string> to return the source fields that are specified as a comma-separated list that supports wildcard (*) patterns.
_source_excludes string | array[string]

A comma-separated list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter. If the _source parameter is false, this parameter is ignored.
_source_includes string | array[string]

A comma-separated list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the _source_excludes query parameter. If the _source parameter is false, this parameter is ignored.
seq_no_primary_term boolean

If true, the request returns the sequence number and primary term of the last modification of each hit.
q string

A query in the Lucene query string syntax. Query parameter searches do not support the full Elasticsearch Query DSL but are handy for testing.

IMPORTANT: This parameter overrides the query parameter in the request body. If both parameters are specified, documents matching the query request body parameter are not returned.
size number

The number of hits to return. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
from number

The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
sort string | array[string]

A comma-separated list of <field>:<direction> pairs.
force_synthetic_source boolean

Should this request force synthetic _source? Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. Fetches with this enabled will be slower the enabling synthetic source natively in the index.

application/json

Body

aggregations object

Defines the aggregations that are run as part of the search request.

External documentation
collapse object
Hide collapse attributes Show collapse attributes object
- field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- inner_hits object | array[object]
 
 The number of inner hits and their sort order
 
 One of:
 InnerHits object array-2 array[object]
 
 Hide attributes Show attributes
 
 name string
 
 size number
 
 The maximum number of hits to return per inner_hits.
 
 from number
 
 Inner hit starting document offset.
 
 collapse object
 
 docvalue_fields array[object]
 
 Hide docvalue_fields attributes Show docvalue_fields attributes object
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 format string
 
 The format in which the values are returned.
 
 include_unmapped boolean
 
 explain boolean
 
 highlight object
 
 Hide highlight attributes Show highlight attributes object
 
 type string
 
 Any of:
 HighlighterType string HighlighterType string
 
 Values are plain, fvh, or unified.
 
 boundary_chars string
 
 A string that contains each boundary character.
 
 boundary_max_scan number
 
 How far to scan for boundary characters.
 
 boundary_scanner string
 
 Values are chars, sentence, or word.
 
 boundary_scanner_locale string
 
 Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".
 
 force_source boolean Deprecated
 
 fragmenter string
 
 Values are simple or span.
 
 fragment_size number
 
 The size of the highlighted fragment in characters.
 
 highlight_filter boolean
 
 highlight_query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
 
 max_fragment_length number
 
 max_analyzed_offset number
 
 If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.
 
 no_match_size number
 
 The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
 
 number_of_fragments number
 
 The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.
 
 options object
 
 Hide options attribute Show options attribute object
 
 * object Additional properties
 
 order string
 
 Value is score.
 
 phrase_limit number
 
 Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.
 
 post_tags array[string]
 
 Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
 
 pre_tags array[string]
 
 Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
 
 require_field_match boolean
 
 By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.
 
 tags_schema string
 
 Value is styled.
 
 encoder string
 
 Values are default or html.
 
 fields object Required
 
 ignore_unmapped boolean
 
 script_fields object
 
 Hide script_fields attribute Show script_fields attribute object
 
 * object Additional properties
 
 Hide * attributes Show * attributes object
 
 script object Required
 
 Hide script attributes Show script attributes object
 
 source
 
 id string
 
 params object
 
 Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
 
 lang
 
 options object
 
 ignore_failure boolean
 
 seq_no_primary_term boolean
 
 fields string | array[string]
 
 sort string | object | array[string | object]
 
 One of:
 Field string SortOptions object Sort array[string | object]
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 _source boolean | object
 
 Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
 
 One of:
 SourceConfig boolean SourceFilter object
 
 stored_fields string | array[string]
 
 track_scores boolean
 
 version boolean
 
 Hide attributes Show attributes object
 
 name string
 
 size number
 
 The maximum number of hits to return per inner_hits.
 
 from number
 
 Inner hit starting document offset.
 
 collapse object
 
 docvalue_fields array[object]
 
 Hide docvalue_fields attributes Show docvalue_fields attributes object
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 format string
 
 The format in which the values are returned.
 
 include_unmapped boolean
 
 explain boolean
 
 highlight object
 
 Hide highlight attributes Show highlight attributes object
 
 type
 
 boundary_chars string
 
 A string that contains each boundary character.
 
 boundary_max_scan number
 
 How far to scan for boundary characters.
 
 boundary_scanner string
 
 Values are chars, sentence, or word.
 
 boundary_scanner_locale string
 
 Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".
 
 force_source boolean Deprecated
 
 fragmenter string
 
 Values are simple or span.
 
 fragment_size number
 
 The size of the highlighted fragment in characters.
 
 highlight_filter boolean
 
 highlight_query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 max_fragment_length number
 
 max_analyzed_offset number
 
 If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.
 
 no_match_size number
 
 The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
 
 number_of_fragments number
 
 The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.
 
 options object
 
 order string
 
 Value is score.
 
 phrase_limit number
 
 Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.
 
 post_tags array[string]
 
 Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
 
 pre_tags array[string]
 
 Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
 
 require_field_match boolean
 
 By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.
 
 tags_schema string
 
 Value is styled.
 
 encoder string
 
 Values are default or html.
 
 fields object Required
 
 ignore_unmapped boolean
 
 script_fields object
 
 Hide script_fields attribute Show script_fields attribute object
 
 * object Additional properties
 
 Hide * attributes Show * attributes object
 
 script object Required
 
 ignore_failure boolean
 
 seq_no_primary_term boolean
 
 fields string | array[string]
 
 sort string | object | array[string | object]
 
 One of:
 Field string SortOptions object Sort array[string | object]
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 _source boolean | object
 
 Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
 
 One of:
 SourceConfig boolean SourceFilter object
 
 stored_fields string | array[string]
 
 track_scores boolean
 
 version boolean
- max_concurrent_group_searches number
 
 The number of concurrent requests allowed to retrieve the inner_hits per group
- collapse object
explain boolean

If true, the request returns detailed information about score computation as part of a hit.
ext object

Configuration of search extensions defined by Elasticsearch plugins.
Hide ext attribute Show ext attribute object
- * object Additional properties
from number

The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
highlight object
Hide highlight attributes Show highlight attributes object
- type string
 
 Any of:
 HighlighterType string HighlighterType string
 
 Values are plain, fvh, or unified.
- boundary_chars string
 
 A string that contains each boundary character.
- boundary_max_scan number
 
 How far to scan for boundary characters.
- boundary_scanner string
 
 Values are chars, sentence, or word.
- boundary_scanner_locale string
 
 Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".
- force_source boolean Deprecated
- fragmenter string
 
 Values are simple or span.
- fragment_size number
 
 The size of the highlighted fragment in characters.
- highlight_filter boolean
- highlight_query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
- max_fragment_length number
- max_analyzed_offset number
 
 If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.
- no_match_size number
 
 The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
- number_of_fragments number
 
 The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.
- options object
 Hide options attribute Show options attribute object
 
 * object Additional properties
- order string
 
 Value is score.
- phrase_limit number
 
 Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.
- post_tags array[string]
 
 Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
- pre_tags array[string]
 
 Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
- require_field_match boolean
 
 By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.
- tags_schema string
 
 Value is styled.
- encoder string
 
 Values are default or html.
- fields object Required
track_total_hits boolean | number

Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
indices_boost array[object]

Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.

External documentation
Hide indices_boost attribute Show indices_boost attribute object
- * number Additional properties
docvalue_fields array[object]

An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.

External documentation
Hide docvalue_fields attributes Show docvalue_fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
knn object | array[object]

The approximate kNN search to run.
One of:
KnnSearch object array-2 array[object]
Hide attributes Show attributes

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

query_vector array[number]

query_vector_builder object

Hide query_vector_builder attribute Show query_vector_builder attribute object

text_embedding object

Hide text_embedding attributes Show text_embedding attributes object

model_id string Required

model_text string Required

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter object | array[object]

Filters for the kNN search query

One of:
QueryContainer object array-2 array[object]

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

External documentation

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

Hide inner_hits attributes Show inner_hits attributes object

name string

size number

The maximum number of hits to return per inner_hits.

from number

Inner hit starting document offset.

collapse object

Hide collapse attributes Show collapse attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

inner_hits object | array[object]

The number of inner hits and their sort order

One of:
InnerHits object array-2 array[object]

max_concurrent_group_searches number

The number of concurrent requests allowed to retrieve the inner_hits per group

collapse object

docvalue_fields array[object]

Hide docvalue_fields attributes Show docvalue_fields attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

format string

The format in which the values are returned.

include_unmapped boolean

explain boolean

highlight object

Hide highlight attributes Show highlight attributes object

type string

Any of:
HighlighterType string HighlighterType string

Values are plain, fvh, or unified.

boundary_chars string

A string that contains each boundary character.

boundary_max_scan number

How far to scan for boundary characters.

boundary_scanner string

Values are chars, sentence, or word.

boundary_scanner_locale string

Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".

force_source boolean Deprecated

fragmenter string

Values are simple or span.

fragment_size number

The size of the highlighted fragment in characters.

highlight_filter boolean

highlight_query object

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

External documentation

max_fragment_length number

max_analyzed_offset number

If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.

no_match_size number

The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.

number_of_fragments number

The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.

options object

Hide options attribute Show options attribute object

* object Additional properties

order string

Value is score.

phrase_limit number

Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.

post_tags array[string]

Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.

pre_tags array[string]

Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.

require_field_match boolean

By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.

tags_schema string

Value is styled.

encoder string

Values are default or html.

fields object Required

ignore_unmapped boolean

script_fields object

Hide script_fields attribute Show script_fields attribute object

* object Additional properties

Hide * attributes Show * attributes object

script object Required

Hide script attributes Show script attributes object

source

id string

params object

Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

lang

options object

ignore_failure boolean

seq_no_primary_term boolean

fields string | array[string]

sort string | object | array[string | object]

One of:
Field string SortOptions object Sort array[string | object]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.

One of:
SourceConfig boolean SourceFilter object

stored_fields string | array[string]

track_scores boolean

version boolean

rescore_vector object

Hide rescore_vector attribute Show rescore_vector attribute object

oversample number Required

Applies the specified oversample factor to k on the approximate kNN search
External documentation
Hide attributes Show attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

query_vector array[number]

query_vector_builder object

Hide query_vector_builder attribute Show query_vector_builder attribute object

text_embedding object

Hide text_embedding attributes Show text_embedding attributes object

model_id string Required

model_text string Required

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter object | array[object]

Filters for the kNN search query

One of:
QueryContainer object array-2 array[object]

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

External documentation

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

Hide inner_hits attributes Show inner_hits attributes object

name string

size number

The maximum number of hits to return per inner_hits.

from number

Inner hit starting document offset.

collapse object

Hide collapse attributes Show collapse attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

inner_hits object | array[object]

The number of inner hits and their sort order

One of:
InnerHits object array-2 array[object]

max_concurrent_group_searches number

The number of concurrent requests allowed to retrieve the inner_hits per group

collapse object

docvalue_fields array[object]

Hide docvalue_fields attributes Show docvalue_fields attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

format string

The format in which the values are returned.

include_unmapped boolean

explain boolean

highlight object

Hide highlight attributes Show highlight attributes object

type

boundary_chars string

A string that contains each boundary character.

boundary_max_scan number

How far to scan for boundary characters.

boundary_scanner string

Values are chars, sentence, or word.

boundary_scanner_locale string

Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".

force_source boolean Deprecated

fragmenter string

Values are simple or span.

fragment_size number

The size of the highlighted fragment in characters.

highlight_filter boolean

highlight_query object

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

max_fragment_length number

max_analyzed_offset number

If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.

no_match_size number

The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.

number_of_fragments number

The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.

options object

order string

Value is score.

phrase_limit number

Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.

post_tags array[string]

Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.

pre_tags array[string]

Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.

require_field_match boolean

By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.

tags_schema string

Value is styled.

encoder string

Values are default or html.

fields object Required

ignore_unmapped boolean

script_fields object

Hide script_fields attribute Show script_fields attribute object

* object Additional properties

Hide * attributes Show * attributes object

script object Required

ignore_failure boolean

seq_no_primary_term boolean

fields string | array[string]

sort string | object | array[string | object]

One of:
Field string SortOptions object Sort array[string | object]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.

One of:
SourceConfig boolean SourceFilter object

stored_fields string | array[string]

track_scores boolean

version boolean

rescore_vector object

Hide rescore_vector attribute Show rescore_vector attribute object

oversample number Required

Applies the specified oversample factor to k on the approximate kNN search
rank object
Hide rank attribute Show rank attribute object
- rrf object
  Hide rrf attributes Show rrf attributes object
  
  rank_constant number
  
  How much influence documents in individual result sets per query have over the final ranked result set
  
  rank_window_size number
  
  Size of the individual result sets per query
min_score number

The minimum _score for matching documents. Documents with a lower _score are not included in search results and results collected by aggregations.
post_filter object

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

External documentation
profile boolean

Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
query object

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

External documentation
rescore object | array[object]

Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the query and post_filter phases.
One of:
Rescore object array-2 array[object]
Hide attributes Show attributes

window_size number

query object

Hide query attributes Show query attributes object

rescore_query object Required

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

External documentation

query_weight number

Relative importance of the original query versus the rescore query.

rescore_query_weight number

Relative importance of the rescore query versus the original query.

score_mode string

Values are avg, max, min, multiply, or total.

learning_to_rank object

Hide learning_to_rank attributes Show learning_to_rank attributes object

model_id string Required

The unique identifier of the trained model uploaded to Elasticsearch

params object

Named parameters to be passed to the query templates used for feature

Hide params attribute Show params attribute object

* object Additional properties
Hide attributes Show attributes object

window_size number

query object

Hide query attributes Show query attributes object

rescore_query object Required

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

External documentation

query_weight number

Relative importance of the original query versus the rescore query.

rescore_query_weight number

Relative importance of the rescore query versus the original query.

score_mode string

Values are avg, max, min, multiply, or total.

learning_to_rank object

Hide learning_to_rank attributes Show learning_to_rank attributes object

model_id string Required

The unique identifier of the trained model uploaded to Elasticsearch

params object

Named parameters to be passed to the query templates used for feature

Hide params attribute Show params attribute object

* object Additional properties
retriever object
Hide retriever attributes Show retriever attributes object
- standard object
  Hide standard attributes Show standard attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  terminate_after number
  
  Maximum number of documents to collect for each shard.
  
  sort string | object | array[string | object]
  
  One of:
  Field string SortOptions object Sort array[string | object]
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  collapse object
  
  Hide collapse attributes Show collapse attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  inner_hits object | array[object]
  
  The number of inner hits and their sort order
  
  One of:
  InnerHits object array-2 array[object]
  
  Hide attributes Show attributes
  
  name string
  
  size number
  
  The maximum number of hits to return per inner_hits.
  
  from number
  
  Inner hit starting document offset.
  
  collapse object
  
  docvalue_fields array[object]
  
  explain boolean
  
  highlight
  
  ignore_unmapped boolean
  
  script_fields object
  
  seq_no_primary_term boolean
  
  fields string | array[string]
  
  sort
  
  _source
  
  stored_fields string | array[string]
  
  track_scores boolean
  
  version boolean
  
  max_concurrent_group_searches number
  
  The number of concurrent requests allowed to retrieve the inner_hits per group
  
  collapse object
- knn object
  Hide knn attributes Show knn attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  field string Required
  
  The name of the vector field to search against.
  
  query_vector array[number]
  
  query_vector_builder object
  
  Hide query_vector_builder attribute Show query_vector_builder attribute object
  
  text_embedding object
  
  Hide text_embedding attributes Show text_embedding attributes object
  
  model_id string Required
  
  model_text string Required
  
  k number Required
  
  Number of nearest neighbors to return as top hits.
  
  num_candidates number Required
  
  Number of nearest neighbor candidates to consider per shard.
  
  similarity number
  
  The minimum similarity required for a document to be considered a match.
  
  rescore_vector object
  
  Hide rescore_vector attribute Show rescore_vector attribute object
  
  oversample number Required
  
  Applies the specified oversample factor to k on the approximate kNN search
- rrf object
  Hide rrf attributes Show rrf attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  retrievers array[object] Required
  
  A list of child retrievers to specify which sets of returned top documents will have the RRF formula applied to them.
  
  rank_constant number
  
  This value determines how much influence documents in individual result sets per query have over the final ranked result set.
  
  rank_window_size number
  
  This value determines the size of the individual result sets per query.
- text_similarity_reranker object
  Hide text_similarity_reranker attributes Show text_similarity_reranker attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  retriever object Required
  
  rank_window_size number
  
  This value determines how many documents we will consider from the nested retriever.
  
  inference_id string
  
  Unique identifier of the inference endpoint created using the inference API.
  
  inference_text string
  
  The text snippet used as the basis for similarity comparison
  
  field string
  
  The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text
- rule object
  Hide rule attributes Show rule attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  ruleset_ids array[string] Required
  
  The ruleset IDs containing the rules this retriever is evaluating against.
  
  match_criteria object Required
  
  The match criteria that will determine if a rule in the provided rulesets should be applied.
  
  retriever object Required
  
  rank_window_size number
  
  This value determines the size of the individual result set.
script_fields object

Retrieve a script evaluation (based on different fields) for each hit.
Hide script_fields attribute Show script_fields attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  script object Required
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string ScriptSource object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  ignore_failure boolean
search_after array[number | string | boolean | null]

A field value.
size number

The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.
slice object
Hide slice attributes Show slice attributes object
- field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- id string Required
- max number Required
sort string | object | array[string | object]
One of:
Field string SortOptions object Sort array[string | object]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Hide attributes Show attributes

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

Values are min, max, sum, avg, or median.

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

Values are in, ft, yd, mi, nmi, km, m, cm, or mm.

nested object

Hide nested attributes Show nested attributes object

filter object

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

External documentation

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

Hide script attributes Show script attributes object

source string | object

One of:
ScriptSource string ScriptSource object

id string

params object

Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

Hide params attribute Show params attribute object

* object Additional properties

lang string

Any of:
ScriptLanguage string ScriptLanguage string

Values are painless, expression, mustache, or java.

options object

Hide options attribute Show options attribute object

* string Additional properties

type string

Values are string, number, or version.

mode string

Values are min, max, sum, avg, or median.

nested object

Hide nested attributes Show nested attributes object

filter object

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

External documentation

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
One of:
Field string SortOptions object

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

Hide attributes Show attributes

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

Values are min, max, sum, avg, or median.

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

Values are in, ft, yd, mi, nmi, km, m, cm, or mm.

nested object

Hide nested attributes Show nested attributes object

filter object

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

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

Hide script attributes Show script attributes object

source

id string

params object

Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

lang

options object

type string

Values are string, number, or version.

mode string

Values are min, max, sum, avg, or median.

nested object

Hide nested attributes Show nested attributes object

filter object

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

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
One of:
SourceConfig boolean SourceFilter object
Hide attributes Show attributes

excludes string | array[string]

includes string | array[string]
fields array[object]

An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
Hide fields attributes Show fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
suggest object
Hide suggest attribute Show suggest attribute object
- text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters
terminate_after number

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

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

If set to 0 (default), the query does not terminate early.
timeout string

The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
track_scores boolean

If true, calculate and return document scores, even if the scores are not used for sorting.
version boolean

If true, the request returns the document version as part of a hit.
seq_no_primary_term boolean

If true, the request returns sequence number and primary term of the last modification of each hit.

External documentation
stored_fields string | array[string]
pit object
Hide pit attributes Show pit attributes object
- id string Required
- keep_alive string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string ScriptSource object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
stats array[string]

The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.

Responses

200 application/json
Hide response attributes Show response attributes object
- took number Required
  
  The number of milliseconds it took Elasticsearch to run the request. This value is calculated by measuring the time elapsed between receipt of a request on the coordinating node and the time at which the coordinating node is ready to send the response. It includes:
  
  Communication time between the coordinating node and data nodes
  
  Time the request spends in the search thread pool, queued for execution
  
  Actual run time
  
  It does not include:
  
  Time needed to send the request to Elasticsearch
  
  Time needed to serialize the JSON response
  
  Time needed to send the response to a client
- timed_out boolean Required
  
  If true, the request timed out before completion; returned results may be partial or empty.
- _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number
- hits object Required
  
  Hide hits attributes Show hits attributes object
  
  total object | number
  
  Total hit count information, present only if track_total_hits wasn't false in the search request.
  
  One of:
  TotalHits object number-2 number
  
  Hide attributes Show attributes
  
  relation string Required
  
  Values are eq or gte.
  
  value number Required
  
  hits array[object] Required
  
  Hide hits attributes Show hits attributes object
  
  _index string Required
  
  _id string
  
  _score number | string | null
  
  One of:
  number-1 number string-2 string | null
  
  _explanation object
  
  Hide _explanation attributes Show _explanation attributes object
  
  description string Required
  
  details array[object] Required
  
  value number Required
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  highlight object
  
  Hide highlight attribute Show highlight attribute object
  
  * array[string] Additional properties
  
  inner_hits object
  
  Hide inner_hits attribute Show inner_hits attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  hits object Required
  
  matched_queries array[string] | object
  
  One of:
  array-1 array[string] object-2 object
  
  _nested object
  
  Hide _nested attributes Show _nested attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  offset number Required
  
  _nested object
  
  _ignored array[string]
  
  ignored_field_values object
  
  Hide ignored_field_values attribute Show ignored_field_values attribute object
  
  * array[object] Additional properties
  
  _shard string
  
  _node string
  
  _routing string
  
  _source object
  
  _rank number
  
  _seq_no number
  
  _primary_term number
  
  _version number
  
  sort array[number | string | boolean | null]
  
  A field value.
  
  max_score number | string | null
  
  One of:
  number-1 number string-2 string | null
- aggregations object
- _clusters object
  
  Hide _clusters attributes Show _clusters attributes object
  
  skipped number Required
  
  successful number Required
  
  total number Required
  
  running number Required
  
  partial number Required
  
  failed number Required
  
  details object
  
  Hide details attribute Show details attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  status string Required
  
  Values are running, successful, partial, skipped, or failed.
  
  indices string Required
  
  took number
  
  Time unit for milliseconds
  
  timed_out boolean Required
  
  _shards object
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  skipped number
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  shard number Required
  
  status string
- fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
- max_score number
- num_reduce_phases number
- profile object
  
  Hide profile attribute Show profile attribute object
  
  shards array[object] Required
  
  Hide shards attributes Show shards attributes object
  
  aggregations array[object] Required
  
  Hide aggregations attributes Show aggregations attributes object
  
  breakdown object Required
  
  description string Required
  
  time_in_nanos
  
  type string Required
  
  debug object
  
  children array[object]
  
  cluster string Required
  
  dfs object
  
  Hide dfs attributes Show dfs attributes object
  
  statistics object
  
  Hide statistics attributes Show statistics attributes object
  
  type string Required
  
  description string Required
  
  time string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  time_in_nanos
  
  breakdown object Required
  
  debug object
  
  children array[object]
  
  knn array[object]
  
  fetch object
  
  Hide fetch attributes Show fetch attributes object
  
  type string Required
  
  description string Required
  
  time_in_nanos number
  
  Time unit for nanoseconds
  
  breakdown object Required
  
  Hide breakdown attributes Show breakdown attributes object
  
  load_source number
  
  load_source_count number
  
  load_stored_fields number
  
  load_stored_fields_count number
  
  next_reader number
  
  next_reader_count number
  
  process_count number
  
  process number
  
  debug object
  
  Hide debug attributes Show debug attributes object
  
  stored_fields array[string]
  
  fast_path number
  
  children array[object]
  
  id string Required
  
  index string Required
  
  node_id string Required
  
  searches array[object] Required
  
  Hide searches attributes Show searches attributes object
  
  collector array[object] Required
  
  query array[object] Required
  
  rewrite_time number Required
  
  shard_id number Required
- pit_id string
- _scroll_id string
- suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  * array[object] Additional properties
  
  One of:
  CompletionSuggest object PhraseSuggest object TermSuggest object
  
  Hide attributes Show attributes
  
  length number Required
  
  offset number Required
  
  text string Required
  
  options
- terminated_early boolean

GET /{index}/_search

curl \
 --request GET 'http://api.example.com/{index}/_search' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"query\": {\n    \"term\": {\n      \"user.id\": \"kimchy\"\n    }\n  }\n}"'

Request examples

Run `GET /my-index-000001/_search?from=40&size=20` to run a search.

{
  "query": {
    "term": {
      "user.id": "kimchy"
    }
  }
}

Run `POST /_search` to run a point in time search. The `id` parameter tells Elasticsearch to run the request using contexts from this open point in time. The `keep_alive` parameter tells Elasticsearch how long it should extend the time to live of the point in time.

{
    "size": 100,  
    "query": {
        "match" : {
            "title" : "elasticsearch"
        }
    },
    "pit": {
      "id":  "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==", 
      "keep_alive": "1m"  
    }
}

When paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently. The result from running the first `GET /_search` request returns documents belonging to the first slice (`id: 0`). If you run a second request with `id` set to `1', it returns documents in the second slice. Since the maximum number of slices is set to `2`, the union of the results is equivalent to the results of a point-in-time search without slicing.

{
  "slice": {
    "id": 0,                      
    "max": 2                      
  },
  "query": {
    "match": {
      "message": "foo"
    }
  },
  "pit": {
    "id": "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA=="
  }
}

Response examples (200)

An abbreviated response from `GET /my-index-000001/_search?from=40&size=20` with a simple term query.

{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 20,
      "relation": "eq"
    },
    "max_score": 1.3862942,
    "hits": [
      {
        "_index": "my-index-000001",
        "_id": "0",
        "_score": 1.3862942,
        "_source": {
          "@timestamp": "2099-11-15T14:12:12",
          "http": {
            "request": {
              "method": "get"
            },
            "response": {
              "status_code": 200,
              "bytes": 1070000
            },
            "version": "1.1"
          },
          "source": {
            "ip": "127.0.0.1"
          },
          "message": "GET /search HTTP/1.1 200 1070000",
          "user": {
            "id": "kimchy"
          }
        }
      }
    ]
  }
}

Run a search

POST /{index}/_search

Api key auth Basic auth Bearer auth

Get search hits that match the query defined in the request. You can provide search queries using the q query string parameter or the request body. If both are specified, only the query parameter is used.

If the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges. To search a point in time (PIT) for an alias, you must have the read index privilege for the alias's data streams or indices.

Search slicing

When paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the slice and pit properties. By default the splitting is done first on the shards, then locally on each shard. The local splitting partitions the shard into contiguous ranges based on Lucene document IDs.

For instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.

IMPORTANT: The same point-in-time ID should be used for all slices. If different PIT IDs are used, slices can overlap and miss documents. This situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.

External documentation

Path parameters

index string | array[string] Required

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

If true and there are shard request timeouts or shard failures, the request returns partial results. If false, it returns an error with no partial results.

To override the default behavior, you can set the search.default_allow_partial_results cluster setting to false.
analyzer string

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

If true, wildcard and prefix queries are analyzed. This parameter can be used only when the q query string parameter is specified.
batched_reduce_size number

The number of shard results that should be reduced at once on the coordinating node. If the potential number of shards in the request can be large, this value should be used as a protection mechanism to reduce the memory overhead per search request.
ccs_minimize_roundtrips boolean

If true, network round-trips between the coordinating node and the remote clusters are minimized when running cross-cluster search (CCS) requests.
default_operator string

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

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

The field to use as a default when no field prefix is given in the query string. This parameter can be used only when the q query string parameter is specified.
docvalue_fields string | array[string]

A comma-separated list of fields to return as the docvalue representation of a field for each hit.
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.
explain boolean

If true, the request returns detailed information about score computation as part of a hit.
ignore_throttled boolean Deprecated

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

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

If true, the response includes the score contribution from any named queries.

This functionality reruns each named query on every hit in a search response. Typically, this adds a small overhead to a request. However, using computationally expensive named queries on a large number of hits may add significant overhead.
lenient boolean

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

The number of concurrent shard requests per node that the search runs concurrently. This value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests.
preference string
The nodes and shards used for the search. By default, Elasticsearch selects from eligible nodes and shards using adaptive replica selection, accounting for allocation awareness. Valid values are:
- _only_local to run the search only on shards on the local node.
- _local to, if possible, run the search on shards on the local node, or if not, select shards using the default method.
- _only_nodes:<node-id>,<node-id> to run the search on only the specified nodes IDs. If suitable shards exist on more than one selected node, use shards on those nodes using the default method. If none of the specified nodes are available, select shards from any available node using the default method.
- _prefer_nodes:<node-id>,<node-id> to if possible, run the search on the specified nodes IDs. If not, select shards using the default method. _shards:<shard>,<shard> to run the search only on the specified shards. You can combine this value with other preference values. However, the _shards value must come first. For example: _shards:2,3|_local. <custom-string> (any string that does not start with _) to route searches with the same <custom-string> to the same shards in the same order.
pre_filter_shard_size number
A threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method (if date filters are mandatory to match but the shard bounds and the query are disjoint). When unspecified, the pre-filter phase is executed if any of these conditions is met:
- The request targets more than 128 shards.
- The request targets one or more read-only index.
- The primary sort of the query targets an indexed field.
request_cache boolean

If true, the caching of search results is enabled for requests where size is 0. It defaults to index level settings.
routing string

A custom value that is used to route operations to a specific shard.
scroll string

The period to retain the search context for scrolling. By default, this value cannot exceed 1d (24 hours). You can change this limit by using the search.max_keep_alive cluster-level setting.
search_type string

Indicates how distributed term frequencies are calculated for relevance scoring.

Values are query_then_fetch or dfs_query_then_fetch.
stats array[string]

Specific tag of the request for logging and statistical purposes.
stored_fields string | array[string]

A comma-separated list of stored fields to return as part of a hit. If no fields are specified, no stored fields are included in the response. If this field is specified, the _source parameter defaults to false. You can pass _source: true to return both source fields and stored fields in the search response.
suggest_field string

The field to use for suggestions.
suggest_mode string

The suggest mode. This parameter can be used only when the suggest_field and suggest_text query string parameters are specified.

Values are missing, popular, or always.
suggest_size number

The number of suggestions to return. This parameter can be used only when the suggest_field and suggest_text query string parameters are specified.
suggest_text string

The source text for which the suggestions should be returned. This parameter can be used only when the suggest_field and suggest_text query string parameters are specified.
terminate_after number

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

IMPORTANT: Use with caution. Elasticsearch applies this parameter to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers. If set to 0 (default), the query does not terminate early.
timeout string

The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. It defaults to no timeout.
track_total_hits boolean | number

The number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query.
track_scores boolean

If true, the request calculates and returns document scores, even if the scores are not used for sorting.
typed_keys boolean

If true, aggregation and suggester names are be prefixed by their respective types in the response.
rest_total_hits_as_int boolean

Indicates whether hits.total should be rendered as an integer or an object in the rest search response.
version boolean

If true, the request returns the document version as part of a hit.
_source boolean | string | array[string]
The source fields that are returned for matching documents. These fields are returned in the hits._source property of the search response. Valid values are:
- true to return the entire document source.
- false to not return the document source.
- <string> to return the source fields that are specified as a comma-separated list that supports wildcard (*) patterns.
_source_excludes string | array[string]

A comma-separated list of source fields to exclude from the response. You can also use this parameter to exclude fields from the subset specified in _source_includes query parameter. If the _source parameter is false, this parameter is ignored.
_source_includes string | array[string]

A comma-separated list of source fields to include in the response. If this parameter is specified, only these source fields are returned. You can exclude fields from this subset using the _source_excludes query parameter. If the _source parameter is false, this parameter is ignored.
seq_no_primary_term boolean

If true, the request returns the sequence number and primary term of the last modification of each hit.
q string

A query in the Lucene query string syntax. Query parameter searches do not support the full Elasticsearch Query DSL but are handy for testing.

IMPORTANT: This parameter overrides the query parameter in the request body. If both parameters are specified, documents matching the query request body parameter are not returned.
size number

The number of hits to return. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
from number

The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
sort string | array[string]

A comma-separated list of <field>:<direction> pairs.
force_synthetic_source boolean

Should this request force synthetic _source? Use this to test if the mapping supports synthetic _source and to get a sense of the worst case performance. Fetches with this enabled will be slower the enabling synthetic source natively in the index.

application/json

Body

aggregations object

Defines the aggregations that are run as part of the search request.

External documentation
collapse object
Hide collapse attributes Show collapse attributes object
- field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- inner_hits object | array[object]
 
 The number of inner hits and their sort order
 
 One of:
 InnerHits object array-2 array[object]
 
 Hide attributes Show attributes
 
 name string
 
 size number
 
 The maximum number of hits to return per inner_hits.
 
 from number
 
 Inner hit starting document offset.
 
 collapse object
 
 docvalue_fields array[object]
 
 Hide docvalue_fields attributes Show docvalue_fields attributes object
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 format string
 
 The format in which the values are returned.
 
 include_unmapped boolean
 
 explain boolean
 
 highlight object
 
 Hide highlight attributes Show highlight attributes object
 
 type string
 
 Any of:
 HighlighterType string HighlighterType string
 
 Values are plain, fvh, or unified.
 
 boundary_chars string
 
 A string that contains each boundary character.
 
 boundary_max_scan number
 
 How far to scan for boundary characters.
 
 boundary_scanner string
 
 Values are chars, sentence, or word.
 
 boundary_scanner_locale string
 
 Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".
 
 force_source boolean Deprecated
 
 fragmenter string
 
 Values are simple or span.
 
 fragment_size number
 
 The size of the highlighted fragment in characters.
 
 highlight_filter boolean
 
 highlight_query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
 
 max_fragment_length number
 
 max_analyzed_offset number
 
 If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.
 
 no_match_size number
 
 The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
 
 number_of_fragments number
 
 The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.
 
 options object
 
 Hide options attribute Show options attribute object
 
 * object Additional properties
 
 order string
 
 Value is score.
 
 phrase_limit number
 
 Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.
 
 post_tags array[string]
 
 Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
 
 pre_tags array[string]
 
 Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
 
 require_field_match boolean
 
 By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.
 
 tags_schema string
 
 Value is styled.
 
 encoder string
 
 Values are default or html.
 
 fields object Required
 
 ignore_unmapped boolean
 
 script_fields object
 
 Hide script_fields attribute Show script_fields attribute object
 
 * object Additional properties
 
 Hide * attributes Show * attributes object
 
 script object Required
 
 Hide script attributes Show script attributes object
 
 source
 
 id string
 
 params object
 
 Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
 
 lang
 
 options object
 
 ignore_failure boolean
 
 seq_no_primary_term boolean
 
 fields string | array[string]
 
 sort string | object | array[string | object]
 
 One of:
 Field string SortOptions object Sort array[string | object]
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 _source boolean | object
 
 Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
 
 One of:
 SourceConfig boolean SourceFilter object
 
 stored_fields string | array[string]
 
 track_scores boolean
 
 version boolean
 
 Hide attributes Show attributes object
 
 name string
 
 size number
 
 The maximum number of hits to return per inner_hits.
 
 from number
 
 Inner hit starting document offset.
 
 collapse object
 
 docvalue_fields array[object]
 
 Hide docvalue_fields attributes Show docvalue_fields attributes object
 
 field string Required
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 format string
 
 The format in which the values are returned.
 
 include_unmapped boolean
 
 explain boolean
 
 highlight object
 
 Hide highlight attributes Show highlight attributes object
 
 type
 
 boundary_chars string
 
 A string that contains each boundary character.
 
 boundary_max_scan number
 
 How far to scan for boundary characters.
 
 boundary_scanner string
 
 Values are chars, sentence, or word.
 
 boundary_scanner_locale string
 
 Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".
 
 force_source boolean Deprecated
 
 fragmenter string
 
 Values are simple or span.
 
 fragment_size number
 
 The size of the highlighted fragment in characters.
 
 highlight_filter boolean
 
 highlight_query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 max_fragment_length number
 
 max_analyzed_offset number
 
 If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.
 
 no_match_size number
 
 The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
 
 number_of_fragments number
 
 The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.
 
 options object
 
 order string
 
 Value is score.
 
 phrase_limit number
 
 Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.
 
 post_tags array[string]
 
 Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
 
 pre_tags array[string]
 
 Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
 
 require_field_match boolean
 
 By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.
 
 tags_schema string
 
 Value is styled.
 
 encoder string
 
 Values are default or html.
 
 fields object Required
 
 ignore_unmapped boolean
 
 script_fields object
 
 Hide script_fields attribute Show script_fields attribute object
 
 * object Additional properties
 
 Hide * attributes Show * attributes object
 
 script object Required
 
 ignore_failure boolean
 
 seq_no_primary_term boolean
 
 fields string | array[string]
 
 sort string | object | array[string | object]
 
 One of:
 Field string SortOptions object Sort array[string | object]
 
 Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
 
 _source boolean | object
 
 Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
 
 One of:
 SourceConfig boolean SourceFilter object
 
 stored_fields string | array[string]
 
 track_scores boolean
 
 version boolean
- max_concurrent_group_searches number
 
 The number of concurrent requests allowed to retrieve the inner_hits per group
- collapse object
explain boolean

If true, the request returns detailed information about score computation as part of a hit.
ext object

Configuration of search extensions defined by Elasticsearch plugins.
Hide ext attribute Show ext attribute object
- * object Additional properties
from number

The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
highlight object
Hide highlight attributes Show highlight attributes object
- type string
 
 Any of:
 HighlighterType string HighlighterType string
 
 Values are plain, fvh, or unified.
- boundary_chars string
 
 A string that contains each boundary character.
- boundary_max_scan number
 
 How far to scan for boundary characters.
- boundary_scanner string
 
 Values are chars, sentence, or word.
- boundary_scanner_locale string
 
 Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".
- force_source boolean Deprecated
- fragmenter string
 
 Values are simple or span.
- fragment_size number
 
 The size of the highlighted fragment in characters.
- highlight_filter boolean
- highlight_query object
 
 An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
 
 External documentation
- max_fragment_length number
- max_analyzed_offset number
 
 If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.
- no_match_size number
 
 The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.
- number_of_fragments number
 
 The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.
- options object
 Hide options attribute Show options attribute object
 
 * object Additional properties
- order string
 
 Value is score.
- phrase_limit number
 
 Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.
- post_tags array[string]
 
 Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
- pre_tags array[string]
 
 Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.
- require_field_match boolean
 
 By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.
- tags_schema string
 
 Value is styled.
- encoder string
 
 Values are default or html.
- fields object Required
track_total_hits boolean | number

Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
indices_boost array[object]

Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.

External documentation
Hide indices_boost attribute Show indices_boost attribute object
- * number Additional properties
docvalue_fields array[object]

An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.

External documentation
Hide docvalue_fields attributes Show docvalue_fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
knn object | array[object]

The approximate kNN search to run.
One of:
KnnSearch object array-2 array[object]
Hide attributes Show attributes

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

query_vector array[number]

query_vector_builder object

Hide query_vector_builder attribute Show query_vector_builder attribute object

text_embedding object

Hide text_embedding attributes Show text_embedding attributes object

model_id string Required

model_text string Required

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter object | array[object]

Filters for the kNN search query

One of:
QueryContainer object array-2 array[object]

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

External documentation

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

Hide inner_hits attributes Show inner_hits attributes object

name string

size number

The maximum number of hits to return per inner_hits.

from number

Inner hit starting document offset.

collapse object

Hide collapse attributes Show collapse attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

inner_hits object | array[object]

The number of inner hits and their sort order

One of:
InnerHits object array-2 array[object]

max_concurrent_group_searches number

The number of concurrent requests allowed to retrieve the inner_hits per group

collapse object

docvalue_fields array[object]

Hide docvalue_fields attributes Show docvalue_fields attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

format string

The format in which the values are returned.

include_unmapped boolean

explain boolean

highlight object

Hide highlight attributes Show highlight attributes object

type string

Any of:
HighlighterType string HighlighterType string

Values are plain, fvh, or unified.

boundary_chars string

A string that contains each boundary character.

boundary_max_scan number

How far to scan for boundary characters.

boundary_scanner string

Values are chars, sentence, or word.

boundary_scanner_locale string

Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".

force_source boolean Deprecated

fragmenter string

Values are simple or span.

fragment_size number

The size of the highlighted fragment in characters.

highlight_filter boolean

highlight_query object

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

External documentation

max_fragment_length number

max_analyzed_offset number

If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.

no_match_size number

The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.

number_of_fragments number

The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.

options object

Hide options attribute Show options attribute object

* object Additional properties

order string

Value is score.

phrase_limit number

Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.

post_tags array[string]

Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.

pre_tags array[string]

Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.

require_field_match boolean

By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.

tags_schema string

Value is styled.

encoder string

Values are default or html.

fields object Required

ignore_unmapped boolean

script_fields object

Hide script_fields attribute Show script_fields attribute object

* object Additional properties

Hide * attributes Show * attributes object

script object Required

Hide script attributes Show script attributes object

source

id string

params object

Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

lang

options object

ignore_failure boolean

seq_no_primary_term boolean

fields string | array[string]

sort string | object | array[string | object]

One of:
Field string SortOptions object Sort array[string | object]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.

One of:
SourceConfig boolean SourceFilter object

stored_fields string | array[string]

track_scores boolean

version boolean

rescore_vector object

Hide rescore_vector attribute Show rescore_vector attribute object

oversample number Required

Applies the specified oversample factor to k on the approximate kNN search
External documentation
Hide attributes Show attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

query_vector array[number]

query_vector_builder object

Hide query_vector_builder attribute Show query_vector_builder attribute object

text_embedding object

Hide text_embedding attributes Show text_embedding attributes object

model_id string Required

model_text string Required

k number

The final number of nearest neighbors to return as top hits

num_candidates number

The number of nearest neighbor candidates to consider per shard

boost number

Boost value to apply to kNN scores

filter object | array[object]

Filters for the kNN search query

One of:
QueryContainer object array-2 array[object]

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

External documentation

similarity number

The minimum similarity for a vector to be considered a match

inner_hits object

Hide inner_hits attributes Show inner_hits attributes object

name string

size number

The maximum number of hits to return per inner_hits.

from number

Inner hit starting document offset.

collapse object

Hide collapse attributes Show collapse attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

inner_hits object | array[object]

The number of inner hits and their sort order

One of:
InnerHits object array-2 array[object]

max_concurrent_group_searches number

The number of concurrent requests allowed to retrieve the inner_hits per group

collapse object

docvalue_fields array[object]

Hide docvalue_fields attributes Show docvalue_fields attributes object

field string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

format string

The format in which the values are returned.

include_unmapped boolean

explain boolean

highlight object

Hide highlight attributes Show highlight attributes object

type

boundary_chars string

A string that contains each boundary character.

boundary_max_scan number

How far to scan for boundary characters.

boundary_scanner string

Values are chars, sentence, or word.

boundary_scanner_locale string

Controls which locale is used to search for sentence and word boundaries. This parameter takes a form of a language tag, for example: "en-US", "fr-FR", "ja-JP".

force_source boolean Deprecated

fragmenter string

Values are simple or span.

fragment_size number

The size of the highlighted fragment in characters.

highlight_filter boolean

highlight_query object

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

max_fragment_length number

max_analyzed_offset number

If set to a non-negative value, highlighting stops at this defined maximum limit. The rest of the text is not processed, thus not highlighted and no error is returned The max_analyzed_offset query setting does not override the index.highlight.max_analyzed_offset setting, which prevails when it’s set to lower value than the query setting.

no_match_size number

The amount of text you want to return from the beginning of the field if there are no matching fragments to highlight.

number_of_fragments number

The maximum number of fragments to return. If the number of fragments is set to 0, no fragments are returned. Instead, the entire field contents are highlighted and returned. This can be handy when you need to highlight short texts such as a title or address, but fragmentation is not required. If number_of_fragments is 0, fragment_size is ignored.

options object

order string

Value is score.

phrase_limit number

Controls the number of matching phrases in a document that are considered. Prevents the fvh highlighter from analyzing too many phrases and consuming too much memory. When using matched_fields, phrase_limit phrases per matched field are considered. Raising the limit increases query time and consumes more memory. Only supported by the fvh highlighter.

post_tags array[string]

Use in conjunction with pre_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.

pre_tags array[string]

Use in conjunction with post_tags to define the HTML tags to use for the highlighted text. By default, highlighted text is wrapped in  and  tags.

require_field_match boolean

By default, only fields that contains a query match are highlighted. Set to false to highlight all fields.

tags_schema string

Value is styled.

encoder string

Values are default or html.

fields object Required

ignore_unmapped boolean

script_fields object

Hide script_fields attribute Show script_fields attribute object

* object Additional properties

Hide * attributes Show * attributes object

script object Required

ignore_failure boolean

seq_no_primary_term boolean

fields string | array[string]

sort string | object | array[string | object]

One of:
Field string SortOptions object Sort array[string | object]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.

One of:
SourceConfig boolean SourceFilter object

stored_fields string | array[string]

track_scores boolean

version boolean

rescore_vector object

Hide rescore_vector attribute Show rescore_vector attribute object

oversample number Required

Applies the specified oversample factor to k on the approximate kNN search
rank object
Hide rank attribute Show rank attribute object
- rrf object
  Hide rrf attributes Show rrf attributes object
  
  rank_constant number
  
  How much influence documents in individual result sets per query have over the final ranked result set
  
  rank_window_size number
  
  Size of the individual result sets per query
min_score number

The minimum _score for matching documents. Documents with a lower _score are not included in search results and results collected by aggregations.
post_filter object

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

External documentation
profile boolean

Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
query object

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

External documentation
rescore object | array[object]

Can be used to improve precision by reordering just the top (for example 100 - 500) documents returned by the query and post_filter phases.
One of:
Rescore object array-2 array[object]
Hide attributes Show attributes

window_size number

query object

Hide query attributes Show query attributes object

rescore_query object Required

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

External documentation

query_weight number

Relative importance of the original query versus the rescore query.

rescore_query_weight number

Relative importance of the rescore query versus the original query.

score_mode string

Values are avg, max, min, multiply, or total.

learning_to_rank object

Hide learning_to_rank attributes Show learning_to_rank attributes object

model_id string Required

The unique identifier of the trained model uploaded to Elasticsearch

params object

Named parameters to be passed to the query templates used for feature

Hide params attribute Show params attribute object

* object Additional properties
Hide attributes Show attributes object

window_size number

query object

Hide query attributes Show query attributes object

rescore_query object Required

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

External documentation

query_weight number

Relative importance of the original query versus the rescore query.

rescore_query_weight number

Relative importance of the rescore query versus the original query.

score_mode string

Values are avg, max, min, multiply, or total.

learning_to_rank object

Hide learning_to_rank attributes Show learning_to_rank attributes object

model_id string Required

The unique identifier of the trained model uploaded to Elasticsearch

params object

Named parameters to be passed to the query templates used for feature

Hide params attribute Show params attribute object

* object Additional properties
retriever object
Hide retriever attributes Show retriever attributes object
- standard object
  Hide standard attributes Show standard attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  query object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  search_after array[number | string | boolean | null]
  
  A field value.
  
  terminate_after number
  
  Maximum number of documents to collect for each shard.
  
  sort string | object | array[string | object]
  
  One of:
  Field string SortOptions object Sort array[string | object]
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  collapse object
  
  Hide collapse attributes Show collapse attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  inner_hits object | array[object]
  
  The number of inner hits and their sort order
  
  One of:
  InnerHits object array-2 array[object]
  
  Hide attributes Show attributes
  
  name string
  
  size number
  
  The maximum number of hits to return per inner_hits.
  
  from number
  
  Inner hit starting document offset.
  
  collapse object
  
  docvalue_fields array[object]
  
  explain boolean
  
  highlight
  
  ignore_unmapped boolean
  
  script_fields object
  
  seq_no_primary_term boolean
  
  fields string | array[string]
  
  sort
  
  _source
  
  stored_fields string | array[string]
  
  track_scores boolean
  
  version boolean
  
  max_concurrent_group_searches number
  
  The number of concurrent requests allowed to retrieve the inner_hits per group
  
  collapse object
- knn object
  Hide knn attributes Show knn attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  field string Required
  
  The name of the vector field to search against.
  
  query_vector array[number]
  
  query_vector_builder object
  
  Hide query_vector_builder attribute Show query_vector_builder attribute object
  
  text_embedding object
  
  Hide text_embedding attributes Show text_embedding attributes object
  
  model_id string Required
  
  model_text string Required
  
  k number Required
  
  Number of nearest neighbors to return as top hits.
  
  num_candidates number Required
  
  Number of nearest neighbor candidates to consider per shard.
  
  similarity number
  
  The minimum similarity required for a document to be considered a match.
  
  rescore_vector object
  
  Hide rescore_vector attribute Show rescore_vector attribute object
  
  oversample number Required
  
  Applies the specified oversample factor to k on the approximate kNN search
- rrf object
  Hide rrf attributes Show rrf attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  retrievers array[object] Required
  
  A list of child retrievers to specify which sets of returned top documents will have the RRF formula applied to them.
  
  rank_constant number
  
  This value determines how much influence documents in individual result sets per query have over the final ranked result set.
  
  rank_window_size number
  
  This value determines the size of the individual result sets per query.
- text_similarity_reranker object
  Hide text_similarity_reranker attributes Show text_similarity_reranker attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  retriever object Required
  
  rank_window_size number
  
  This value determines how many documents we will consider from the nested retriever.
  
  inference_id string
  
  Unique identifier of the inference endpoint created using the inference API.
  
  inference_text string
  
  The text snippet used as the basis for similarity comparison
  
  field string
  
  The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text
- rule object
  Hide rule attributes Show rule attributes object
  
  filter object | array[object]
  
  Query to filter the documents that can match.
  
  One of:
  QueryContainer object array-2 array[object]
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation
  
  min_score number
  
  Minimum _score for matching documents. Documents with a lower _score are not included in the top documents.
  
  ruleset_ids array[string] Required
  
  The ruleset IDs containing the rules this retriever is evaluating against.
  
  match_criteria object Required
  
  The match criteria that will determine if a rule in the provided rulesets should be applied.
  
  retriever object Required
  
  rank_window_size number
  
  This value determines the size of the individual result set.
script_fields object

Retrieve a script evaluation (based on different fields) for each hit.
Hide script_fields attribute Show script_fields attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  script object Required
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string ScriptSource object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  ignore_failure boolean
search_after array[number | string | boolean | null]

A field value.
size number

The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.
slice object
Hide slice attributes Show slice attributes object
- field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- id string Required
- max number Required
sort string | object | array[string | object]
One of:
Field string SortOptions object Sort array[string | object]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Hide attributes Show attributes

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

Values are min, max, sum, avg, or median.

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

Values are in, ft, yd, mi, nmi, km, m, cm, or mm.

nested object

Hide nested attributes Show nested attributes object

filter object

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

External documentation

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

Hide script attributes Show script attributes object

source string | object

One of:
ScriptSource string ScriptSource object

id string

params object

Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

Hide params attribute Show params attribute object

* object Additional properties

lang string

Any of:
ScriptLanguage string ScriptLanguage string

Values are painless, expression, mustache, or java.

options object

Hide options attribute Show options attribute object

* string Additional properties

type string

Values are string, number, or version.

mode string

Values are min, max, sum, avg, or median.

nested object

Hide nested attributes Show nested attributes object

filter object

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

External documentation

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
One of:
Field string SortOptions object

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

Hide attributes Show attributes

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

Values are min, max, sum, avg, or median.

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

Values are in, ft, yd, mi, nmi, km, m, cm, or mm.

nested object

Hide nested attributes Show nested attributes object

filter object

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

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

Hide script attributes Show script attributes object

source

id string

params object

Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

lang

options object

type string

Values are string, number, or version.

mode string

Values are min, max, sum, avg, or median.

nested object

Hide nested attributes Show nested attributes object

filter object

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

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
_source boolean | object

Defines how to fetch a source. Fetching can be disabled entirely, or the source can be filtered.
One of:
SourceConfig boolean SourceFilter object
Hide attributes Show attributes

excludes string | array[string]

includes string | array[string]
fields array[object]

An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
Hide fields attributes Show fields attributes object
- field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- format string
  
  The format in which the values are returned.
- include_unmapped boolean
suggest object
Hide suggest attribute Show suggest attribute object
- text string
  
  Global suggest text, to avoid repetition when the same text is used in several suggesters
terminate_after number

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

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

If set to 0 (default), the query does not terminate early.
timeout string

The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
track_scores boolean

If true, calculate and return document scores, even if the scores are not used for sorting.
version boolean

If true, the request returns the document version as part of a hit.
seq_no_primary_term boolean

If true, the request returns sequence number and primary term of the last modification of each hit.

External documentation
stored_fields string | array[string]
pit object
Hide pit attributes Show pit attributes object
- id string Required
- keep_alive string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string ScriptSource object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
stats array[string]

The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.

Responses

200 application/json
Hide response attributes Show response attributes object
- took number Required
  
  The number of milliseconds it took Elasticsearch to run the request. This value is calculated by measuring the time elapsed between receipt of a request on the coordinating node and the time at which the coordinating node is ready to send the response. It includes:
  
  Communication time between the coordinating node and data nodes
  
  Time the request spends in the search thread pool, queued for execution
  
  Actual run time
  
  It does not include:
  
  Time needed to send the request to Elasticsearch
  
  Time needed to serialize the JSON response
  
  Time needed to send the response to a client
- timed_out boolean Required
  
  If true, the request timed out before completion; returned results may be partial or empty.
- _shards object Required
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  Hide reason attributes Show reason attributes object
  
  type string Required
  
  The type of error
  
  reason string
  
  A human-readable explanation of the error, in English.
  
  stack_trace string
  
  The server stack trace. Present only if the error_trace=true parameter was sent with the request.
  
  caused_by object
  
  root_cause array[object]
  
  suppressed array[object]
  
  shard number Required
  
  status string
  
  skipped number
- hits object Required
  
  Hide hits attributes Show hits attributes object
  
  total object | number
  
  Total hit count information, present only if track_total_hits wasn't false in the search request.
  
  One of:
  TotalHits object number-2 number
  
  Hide attributes Show attributes
  
  relation string Required
  
  Values are eq or gte.
  
  value number Required
  
  hits array[object] Required
  
  Hide hits attributes Show hits attributes object
  
  _index string Required
  
  _id string
  
  _score number | string | null
  
  One of:
  number-1 number string-2 string | null
  
  _explanation object
  
  Hide _explanation attributes Show _explanation attributes object
  
  description string Required
  
  details array[object] Required
  
  value number Required
  
  fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  highlight object
  
  Hide highlight attribute Show highlight attribute object
  
  * array[string] Additional properties
  
  inner_hits object
  
  Hide inner_hits attribute Show inner_hits attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  hits object Required
  
  matched_queries array[string] | object
  
  One of:
  array-1 array[string] object-2 object
  
  _nested object
  
  Hide _nested attributes Show _nested attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  offset number Required
  
  _nested object
  
  _ignored array[string]
  
  ignored_field_values object
  
  Hide ignored_field_values attribute Show ignored_field_values attribute object
  
  * array[object] Additional properties
  
  _shard string
  
  _node string
  
  _routing string
  
  _source object
  
  _rank number
  
  _seq_no number
  
  _primary_term number
  
  _version number
  
  sort array[number | string | boolean | null]
  
  A field value.
  
  max_score number | string | null
  
  One of:
  number-1 number string-2 string | null
- aggregations object
- _clusters object
  
  Hide _clusters attributes Show _clusters attributes object
  
  skipped number Required
  
  successful number Required
  
  total number Required
  
  running number Required
  
  partial number Required
  
  failed number Required
  
  details object
  
  Hide details attribute Show details attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  status string Required
  
  Values are running, successful, partial, skipped, or failed.
  
  indices string Required
  
  took number
  
  Time unit for milliseconds
  
  timed_out boolean Required
  
  _shards object
  
  Hide _shards attributes Show _shards attributes object
  
  failed number Required
  
  successful number Required
  
  total number Required
  
  failures array[object]
  
  skipped number
  
  failures array[object]
  
  Hide failures attributes Show failures attributes object
  
  index string
  
  node string
  
  reason object Required
  
  shard number Required
  
  status string
- fields object
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
- max_score number
- num_reduce_phases number
- profile object
  
  Hide profile attribute Show profile attribute object
  
  shards array[object] Required
  
  Hide shards attributes Show shards attributes object
  
  aggregations array[object] Required
  
  Hide aggregations attributes Show aggregations attributes object
  
  breakdown object Required
  
  description string Required
  
  time_in_nanos
  
  type string Required
  
  debug object
  
  children array[object]
  
  cluster string Required
  
  dfs object
  
  Hide dfs attributes Show dfs attributes object
  
  statistics object
  
  Hide statistics attributes Show statistics attributes object
  
  type string Required
  
  description string Required
  
  time string
  
  A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  
  time_in_nanos
  
  breakdown object Required
  
  debug object
  
  children array[object]
  
  knn array[object]
  
  fetch object
  
  Hide fetch attributes Show fetch attributes object
  
  type string Required
  
  description string Required
  
  time_in_nanos number
  
  Time unit for nanoseconds
  
  breakdown object Required
  
  Hide breakdown attributes Show breakdown attributes object
  
  load_source number
  
  load_source_count number
  
  load_stored_fields number
  
  load_stored_fields_count number
  
  next_reader number
  
  next_reader_count number
  
  process_count number
  
  process number
  
  debug object
  
  Hide debug attributes Show debug attributes object
  
  stored_fields array[string]
  
  fast_path number
  
  children array[object]
  
  id string Required
  
  index string Required
  
  node_id string Required
  
  searches array[object] Required
  
  Hide searches attributes Show searches attributes object
  
  collector array[object] Required
  
  query array[object] Required
  
  rewrite_time number Required
  
  shard_id number Required
- pit_id string
- _scroll_id string
- suggest object
  
  Hide suggest attribute Show suggest attribute object
  
  * array[object] Additional properties
  
  One of:
  CompletionSuggest object PhraseSuggest object TermSuggest object
  
  Hide attributes Show attributes
  
  length number Required
  
  offset number Required
  
  text string Required
  
  options
- terminated_early boolean

POST /{index}/_search

curl \
 --request POST 'http://api.example.com/{index}/_search' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"query\": {\n    \"term\": {\n      \"user.id\": \"kimchy\"\n    }\n  }\n}"'

Request examples

Run `GET /my-index-000001/_search?from=40&size=20` to run a search.

{
  "query": {
    "term": {
      "user.id": "kimchy"
    }
  }
}

Run `POST /_search` to run a point in time search. The `id` parameter tells Elasticsearch to run the request using contexts from this open point in time. The `keep_alive` parameter tells Elasticsearch how long it should extend the time to live of the point in time.

{
    "size": 100,  
    "query": {
        "match" : {
            "title" : "elasticsearch"
        }
    },
    "pit": {
      "id":  "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA==", 
      "keep_alive": "1m"  
    }
}

When paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently. The result from running the first `GET /_search` request returns documents belonging to the first slice (`id: 0`). If you run a second request with `id` set to `1', it returns documents in the second slice. Since the maximum number of slices is set to `2`, the union of the results is equivalent to the results of a point-in-time search without slicing.

{
  "slice": {
    "id": 0,                      
    "max": 2                      
  },
  "query": {
    "match": {
      "message": "foo"
    }
  },
  "pit": {
    "id": "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA=="
  }
}

Response examples (200)

An abbreviated response from `GET /my-index-000001/_search?from=40&size=20` with a simple term query.

{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 20,
      "relation": "eq"
    },
    "max_score": 1.3862942,
    "hits": [
      {
        "_index": "my-index-000001",
        "_id": "0",
        "_score": 1.3862942,
        "_source": {
          "@timestamp": "2099-11-15T14:12:12",
          "http": {
            "request": {
              "method": "get"
            },
            "response": {
              "status_code": 200,
              "bytes": 1070000
            },
            "version": "1.1"
          },
          "source": {
            "ip": "127.0.0.1"
          },
          "message": "GET /search HTTP/1.1 200 1070000",
          "user": {
            "id": "kimchy"
          }
        }
      }
    ]
  }
}

Search a vector tile Added in 7.15.0

GET /{index}/_mvt/{field}/{zoom}/{x}/{y}

Api key auth Basic auth Bearer auth

Search a vector tile for geospatial values. Before using this API, you should be familiar with the Mapbox vector tile specification. The API returns results as a binary mapbox vector tile.

Internally, Elasticsearch translates a vector tile search API request into a search containing:

A geo_bounding_box query on the <field>. The query uses the <zoom>/<x>/<y> tile as a bounding box.
A geotile_grid or geohex_grid aggregation on the <field>. The grid_agg parameter determines the aggregation type. The aggregation uses the <zoom>/<x>/<y> tile as a bounding box.
Optionally, a geo_bounds aggregation on the <field>. The search only includes this aggregation if the exact_bounds parameter is true.
If the optional parameter with_labels is true, the internal search will include a dynamic runtime field that calls the getLabelPosition function of the geometry doc value. This enables the generation of new point features containing suggested geometry labels, so that, for example, multi-polygons will have only one label.

For example, Elasticsearch may translate a vector tile search API request with a grid_agg argument of geotile and an exact_bounds argument of true into the following search

GET my-index/_search
{
  "size": 10000,
  "query": {
    "geo_bounding_box": {
      "my-geo-field": {
        "top_left": {
          "lat": -40.979898069620134,
          "lon": -45
        },
        "bottom_right": {
          "lat": -66.51326044311186,
          "lon": 0
        }
      }
    }
  },
  "aggregations": {
    "grid": {
      "geotile_grid": {
        "field": "my-geo-field",
        "precision": 11,
        "size": 65536,
        "bounds": {
          "top_left": {
            "lat": -40.979898069620134,
            "lon": -45
          },
          "bottom_right": {
            "lat": -66.51326044311186,
            "lon": 0
          }
        }
      }
    },
    "bounds": {
      "geo_bounds": {
        "field": "my-geo-field",
        "wrap_longitude": false
      }
    }
  }
}

The API returns results as a binary Mapbox vector tile. Mapbox vector tiles are encoded as Google Protobufs (PBF). By default, the tile contains three layers:

A hits layer containing a feature for each <field> value matching the geo_bounding_box query.
An aggs layer containing a feature for each cell of the geotile_grid or geohex_grid. The layer only contains features for cells with matching data.
A meta layer containing:
- A feature containing a bounding box. By default, this is the bounding box of the tile.
- Value ranges for any sub-aggregations on the geotile_grid or geohex_grid.
- Metadata for the search.

The API only returns features that can display at its zoom level. For example, if a polygon feature has no area at its zoom level, the API omits it. The API returns errors as UTF-8 encoded JSON.

IMPORTANT: You can specify several options for this API as either a query parameter or request body parameter. If you specify both parameters, the query parameter takes precedence.

Grid precision for geotile

For a grid_agg of geotile, you can use cells in the aggs layer as tiles for lower zoom levels. grid_precision represents the additional zoom levels available through these cells. The final precision is computed by as follows: <zoom> + grid_precision. For example, if <zoom> is 7 and grid_precision is 8, then the geotile_grid aggregation will use a precision of 15. The maximum final precision is 29. The grid_precision also determines the number of cells for the grid as follows: (2^grid_precision) x (2^grid_precision). For example, a value of 8 divides the tile into a grid of 256 x 256 cells. The aggs layer only contains features for cells with matching data.

Grid precision for geohex

For a grid_agg of geohex, Elasticsearch uses <zoom> and grid_precision to calculate a final precision as follows: <zoom> + grid_precision.

This precision determines the H3 resolution of the hexagonal cells produced by the geohex aggregation. The following table maps the H3 resolution for each precision. For example, if <zoom> is 3 and grid_precision is 3, the precision is 6. At a precision of 6, hexagonal cells have an H3 resolution of 2. If <zoom> is 3 and grid_precision is 4, the precision is 7. At a precision of 7, hexagonal cells have an H3 resolution of 3.

Precision	Unique tile bins	H3 resolution	Unique hex bins	Ratio
1	4	0	122	30.5
2	16	0	122	7.625
3	64	1	842	13.15625
4	256	1	842	3.2890625
5	1024	2	5882	5.744140625
6	4096	2	5882	1.436035156
7	16384	3	41162	2.512329102
8	65536	3	41162	0.6280822754
9	262144	4	288122	1.099098206
10	1048576	4	288122	0.2747745514
11	4194304	5	2016842	0.4808526039
12	16777216	6	14117882	0.8414913416
13	67108864	6	14117882	0.2103728354
14	268435456	7	98825162	0.3681524172
15	1073741824	8	691776122	0.644266719
16	4294967296	8	691776122	0.1610666797
17	17179869184	9	4842432842	0.2818666889
18	68719476736	10	33897029882	0.4932667053
19	274877906944	11	237279209162	0.8632167343
20	1099511627776	11	237279209162	0.2158041836
21	4398046511104	12	1660954464122	0.3776573213
22	17592186044416	13	11626681248842	0.6609003122
23	70368744177664	13	11626681248842	0.165225078
24	281474976710656	14	81386768741882	0.2891438866
25	1125899906842620	15	569707381193162	0.5060018015
26	4503599627370500	15	569707381193162	0.1265004504
27	18014398509482000	15	569707381193162	0.03162511259
28	72057594037927900	15	569707381193162	0.007906278149
29	288230376151712000	15	569707381193162	0.001976569537

Hexagonal cells don't align perfectly on a vector tile. Some cells may intersect more than one vector tile. To compute the H3 resolution for each precision, Elasticsearch compares the average density of hexagonal bins at each resolution with the average density of tile bins at each zoom level. Elasticsearch uses the H3 resolution that is closest to the corresponding geotile density.

External documentation

Path parameters

index string | array[string] Required

Comma-separated list of data streams, indices, or aliases to search
field string Required

Field containing geospatial data to return
zoom number Required

Zoom level for the vector tile to search
x number Required

X coordinate for the vector tile to search
y number Required

Y coordinate for the vector tile to search

Query parameters

exact_bounds boolean

If false, the meta layer's feature is the bounding box of the tile. If true, the meta layer's feature is a bounding box resulting from a geo_bounds aggregation. The aggregation runs on values that intersect the // tile with wrap_longitude set to false. The resulting bounding box may be larger than the vector tile.
extent number

The size, in pixels, of a side of the tile. Vector tiles are square with equal sides.
grid_agg string

Aggregation used to create a grid for field.

Values are geotile or geohex.
grid_precision number

Additional zoom levels available through the aggs layer. For example, if is 7 and grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results don't include the aggs layer.
grid_type string

Determines the geometry type for features in the aggs layer. In the aggs layer, each feature represents a geotile_grid cell. If 'grid' each feature is a Polygon of the cells bounding box. If 'point' each feature is a Point that is the centroid of the cell.

Values are grid, point, or centroid.
size number

Maximum number of features to return in the hits layer. Accepts 0-10000. If 0, results don't include the hits layer.
with_labels boolean
If true, the hits and aggs layers will contain additional point features representing suggested label positions for the original features.
- Point and MultiPoint features will have one of the points selected.
- Polygon and MultiPolygon features will have a single point generated, either the centroid, if it is within the polygon, or another point within the polygon selected from the sorted triangle-tree.
- LineString features will likewise provide a roughly central point selected from the triangle-tree.
- The aggregation results will provide one central point for each aggregation bucket.
All attributes from the original features will also be copied to the new label features. In addition, the new features will be distinguishable using the tag _mvt_label_position.

application/json

Body

aggs object
Sub-aggregations for the geotile_grid.

It supports the following aggregation types:
- avg
- boxplot
- cardinality
- extended stats
- max
- median absolute deviation
- min
- percentile
- percentile-rank
- stats
- sum
- value count
The aggregation names can't start with _mvt_. The _mvt_ prefix is reserved for internal aggregations.
buffer number

The size, in pixels, of a clipping buffer outside the tile. This allows renderers to avoid outline artifacts from geometries that extend past the extent of the tile.
exact_bounds boolean

If false, the meta layer's feature is the bounding box of the tile. If true, the meta layer's feature is a bounding box resulting from a geo_bounds aggregation. The aggregation runs on values that intersect the <zoom>/<x>/<y> tile with wrap_longitude set to false. The resulting bounding box may be larger than the vector tile.
extent number

The size, in pixels, of a side of the tile. Vector tiles are square with equal sides.
fields string | array[string]
grid_agg string

Values are geotile or geohex.
grid_precision number

Additional zoom levels available through the aggs layer. For example, if <zoom> is 7 and grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results don't include the aggs layer.
grid_type string

Values are grid, point, or centroid.
query object

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

External documentation
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string ScriptSource object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
size number

The maximum number of features to return in the hits layer. Accepts 0-10000. If 0, results don't include the hits layer.
sort string | object | array[string | object]
One of:
Field string SortOptions object Sort array[string | object]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Hide attributes Show attributes

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

Values are min, max, sum, avg, or median.

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

Values are in, ft, yd, mi, nmi, km, m, cm, or mm.

nested object

Hide nested attributes Show nested attributes object

filter object

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

External documentation

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

Hide script attributes Show script attributes object

source string | object

One of:
ScriptSource string ScriptSource object

id string

params object

Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

Hide params attribute Show params attribute object

* object Additional properties

lang string

Any of:
ScriptLanguage string ScriptLanguage string

Values are painless, expression, mustache, or java.

options object

Hide options attribute Show options attribute object

* string Additional properties

type string

Values are string, number, or version.

mode string

Values are min, max, sum, avg, or median.

nested object

Hide nested attributes Show nested attributes object

filter object

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

External documentation

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
One of:
Field string SortOptions object

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

Hide attributes Show attributes

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

Values are min, max, sum, avg, or median.

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

Values are in, ft, yd, mi, nmi, km, m, cm, or mm.

nested object

Hide nested attributes Show nested attributes object

filter object

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

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

Hide script attributes Show script attributes object

source

id string

params object

Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

lang

options object

type string

Values are string, number, or version.

mode string

Values are min, max, sum, avg, or median.

nested object

Hide nested attributes Show nested attributes object

filter object

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

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
track_total_hits boolean | number

Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
with_labels boolean
If true, the hits and aggs layers will contain additional point features representing suggested label positions for the original features.
- Point and MultiPoint features will have one of the points selected.
- Polygon and MultiPolygon features will have a single point generated, either the centroid, if it is within the polygon, or another point within the polygon selected from the sorted triangle-tree.
- LineString features will likewise provide a roughly central point selected from the triangle-tree.
- The aggregation results will provide one central point for each aggregation bucket.
All attributes from the original features will also be copied to the new label features. In addition, the new features will be distinguishable using the tag _mvt_label_position.

Responses

200 application/json

GET /{index}/_mvt/{field}/{zoom}/{x}/{y}

curl \
 --request GET 'http://api.example.com/{index}/_mvt/{field}/{zoom}/{x}/{y}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"grid_agg\": \"geotile\",\n  \"grid_precision\": 2,\n  \"fields\": [\n    \"name\",\n    \"price\"\n  ],\n  \"query\": {\n    \"term\": {\n      \"included\": true\n    }\n  },\n  \"aggs\": {\n    \"min_price\": {\n      \"min\": {\n        \"field\": \"price\"\n      }\n    },\n    \"max_price\": {\n      \"max\": {\n        \"field\": \"price\"\n      }\n    },\n    \"avg_price\": {\n      \"avg\": {\n        \"field\": \"price\"\n      }\n    }\n  }\n}"'

Request example

Run `GET museums/_mvt/location/13/4207/2692` to search an index for `location` values that intersect the `13/4207/2692` vector tile.

{
  "grid_agg": "geotile",
  "grid_precision": 2,
  "fields": [
    "name",
    "price"
  ],
  "query": {
    "term": {
      "included": true
    }
  },
  "aggs": {
    "min_price": {
      "min": {
        "field": "price"
      }
    },
    "max_price": {
      "max": {
        "field": "price"
      }
    },
    "avg_price": {
      "avg": {
        "field": "price"
      }
    }
  }
}

Response examples (200)

A successful response from `GET museums/_mvt/location/13/4207/2692`. It returns results as a binary vector tile. When decoded into JSON, the tile contains the following data.

{
  "hits": {
    "extent": 4096,
    "version": 2,
    "features": [
      {
        "geometry": {
          "type": "Point",
          "coordinates": [
            3208,
            3864
          ]
        },
        "properties": {
          "_id": "1",
          "_index": "museums",
          "name": "NEMO Science Museum",
          "price": 1750
        },
        "type": 1
      },
      {
        "geometry": {
          "type": "Point",
          "coordinates": [
            3429,
            3496
          ]
        },
        "properties": {
          "_id": "3",
          "_index": "museums",
          "name": "Nederlands Scheepvaartmuseum",
          "price": 1650
        },
        "type": 1
      },
      {
        "geometry": {
          "type": "Point",
          "coordinates": [
            3429,
            3496
          ]
        },
        "properties": {
          "_id": "4",
          "_index": "museums",
          "name": "Amsterdam Centre for Architecture",
          "price": 0
        },
        "type": 1
      }
    ]
  },
  "aggs": {
    "extent": 4096,
    "version": 2,
    "features": [
      {
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                3072,
                3072
              ],
              [
                4096,
                3072
              ],
              [
                4096,
                4096
              ],
              [
                3072,
                4096
              ],
              [
                3072,
                3072
              ]
            ]
          ]
        },
        "properties": {
          "_count": 3,
          "max_price.value": 1750.0,
          "min_price.value": 0.0,
          "avg_price.value": 1133.3333333333333
        },
        "type": 3
      }
    ]
  },
  "meta": {
    "extent": 4096,
    "version": 2,
    "features": [
      {
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                0,
                0
              ],
              [
                4096,
                0
              ],
              [
                4096,
                4096
              ],
              [
                0,
                4096
              ],
              [
                0,
                0
              ]
            ]
          ]
        },
        "properties": {
          "_shards.failed": 0,
          "_shards.skipped": 0,
          "_shards.successful": 1,
          "_shards.total": 1,
          "aggregations._count.avg": 3.0,
          "aggregations._count.count": 1,
          "aggregations._count.max": 3.0,
          "aggregations._count.min": 3.0,
          "aggregations._count.sum": 3.0,
          "aggregations.avg_price.avg": 1133.3333333333333,
          "aggregations.avg_price.count": 1,
          "aggregations.avg_price.max": 1133.3333333333333,
          "aggregations.avg_price.min": 1133.3333333333333,
          "aggregations.avg_price.sum": 1133.3333333333333,
          "aggregations.max_price.avg": 1750.0,
          "aggregations.max_price.count": 1,
          "aggregations.max_price.max": 1750.0,
          "aggregations.max_price.min": 1750.0,
          "aggregations.max_price.sum": 1750.0,
          "aggregations.min_price.avg": 0.0,
          "aggregations.min_price.count": 1,
          "aggregations.min_price.max": 0.0,
          "aggregations.min_price.min": 0.0,
          "aggregations.min_price.sum": 0.0,
          "hits.max_score": 0.0,
          "hits.total.relation": "eq",
          "hits.total.value": 3,
          "timed_out": false,
          "took": 2
        },
        "type": 3
      }
    ]
  }
}

Search a vector tile Added in 7.15.0

POST /{index}/_mvt/{field}/{zoom}/{x}/{y}

Api key auth Basic auth Bearer auth

Search a vector tile for geospatial values. Before using this API, you should be familiar with the Mapbox vector tile specification. The API returns results as a binary mapbox vector tile.

Internally, Elasticsearch translates a vector tile search API request into a search containing:

A geo_bounding_box query on the <field>. The query uses the <zoom>/<x>/<y> tile as a bounding box.
A geotile_grid or geohex_grid aggregation on the <field>. The grid_agg parameter determines the aggregation type. The aggregation uses the <zoom>/<x>/<y> tile as a bounding box.
Optionally, a geo_bounds aggregation on the <field>. The search only includes this aggregation if the exact_bounds parameter is true.
If the optional parameter with_labels is true, the internal search will include a dynamic runtime field that calls the getLabelPosition function of the geometry doc value. This enables the generation of new point features containing suggested geometry labels, so that, for example, multi-polygons will have only one label.

For example, Elasticsearch may translate a vector tile search API request with a grid_agg argument of geotile and an exact_bounds argument of true into the following search

GET my-index/_search
{
  "size": 10000,
  "query": {
    "geo_bounding_box": {
      "my-geo-field": {
        "top_left": {
          "lat": -40.979898069620134,
          "lon": -45
        },
        "bottom_right": {
          "lat": -66.51326044311186,
          "lon": 0
        }
      }
    }
  },
  "aggregations": {
    "grid": {
      "geotile_grid": {
        "field": "my-geo-field",
        "precision": 11,
        "size": 65536,
        "bounds": {
          "top_left": {
            "lat": -40.979898069620134,
            "lon": -45
          },
          "bottom_right": {
            "lat": -66.51326044311186,
            "lon": 0
          }
        }
      }
    },
    "bounds": {
      "geo_bounds": {
        "field": "my-geo-field",
        "wrap_longitude": false
      }
    }
  }
}

The API returns results as a binary Mapbox vector tile. Mapbox vector tiles are encoded as Google Protobufs (PBF). By default, the tile contains three layers:

A hits layer containing a feature for each <field> value matching the geo_bounding_box query.
An aggs layer containing a feature for each cell of the geotile_grid or geohex_grid. The layer only contains features for cells with matching data.
A meta layer containing:
- A feature containing a bounding box. By default, this is the bounding box of the tile.
- Value ranges for any sub-aggregations on the geotile_grid or geohex_grid.
- Metadata for the search.

The API only returns features that can display at its zoom level. For example, if a polygon feature has no area at its zoom level, the API omits it. The API returns errors as UTF-8 encoded JSON.

IMPORTANT: You can specify several options for this API as either a query parameter or request body parameter. If you specify both parameters, the query parameter takes precedence.

Grid precision for geotile

For a grid_agg of geotile, you can use cells in the aggs layer as tiles for lower zoom levels. grid_precision represents the additional zoom levels available through these cells. The final precision is computed by as follows: <zoom> + grid_precision. For example, if <zoom> is 7 and grid_precision is 8, then the geotile_grid aggregation will use a precision of 15. The maximum final precision is 29. The grid_precision also determines the number of cells for the grid as follows: (2^grid_precision) x (2^grid_precision). For example, a value of 8 divides the tile into a grid of 256 x 256 cells. The aggs layer only contains features for cells with matching data.

Grid precision for geohex

For a grid_agg of geohex, Elasticsearch uses <zoom> and grid_precision to calculate a final precision as follows: <zoom> + grid_precision.

This precision determines the H3 resolution of the hexagonal cells produced by the geohex aggregation. The following table maps the H3 resolution for each precision. For example, if <zoom> is 3 and grid_precision is 3, the precision is 6. At a precision of 6, hexagonal cells have an H3 resolution of 2. If <zoom> is 3 and grid_precision is 4, the precision is 7. At a precision of 7, hexagonal cells have an H3 resolution of 3.

Precision	Unique tile bins	H3 resolution	Unique hex bins	Ratio
1	4	0	122	30.5
2	16	0	122	7.625
3	64	1	842	13.15625
4	256	1	842	3.2890625
5	1024	2	5882	5.744140625
6	4096	2	5882	1.436035156
7	16384	3	41162	2.512329102
8	65536	3	41162	0.6280822754
9	262144	4	288122	1.099098206
10	1048576	4	288122	0.2747745514
11	4194304	5	2016842	0.4808526039
12	16777216	6	14117882	0.8414913416
13	67108864	6	14117882	0.2103728354
14	268435456	7	98825162	0.3681524172
15	1073741824	8	691776122	0.644266719
16	4294967296	8	691776122	0.1610666797
17	17179869184	9	4842432842	0.2818666889
18	68719476736	10	33897029882	0.4932667053
19	274877906944	11	237279209162	0.8632167343
20	1099511627776	11	237279209162	0.2158041836
21	4398046511104	12	1660954464122	0.3776573213
22	17592186044416	13	11626681248842	0.6609003122
23	70368744177664	13	11626681248842	0.165225078
24	281474976710656	14	81386768741882	0.2891438866
25	1125899906842620	15	569707381193162	0.5060018015
26	4503599627370500	15	569707381193162	0.1265004504
27	18014398509482000	15	569707381193162	0.03162511259
28	72057594037927900	15	569707381193162	0.007906278149
29	288230376151712000	15	569707381193162	0.001976569537

Hexagonal cells don't align perfectly on a vector tile. Some cells may intersect more than one vector tile. To compute the H3 resolution for each precision, Elasticsearch compares the average density of hexagonal bins at each resolution with the average density of tile bins at each zoom level. Elasticsearch uses the H3 resolution that is closest to the corresponding geotile density.

External documentation

Path parameters

index string | array[string] Required

Comma-separated list of data streams, indices, or aliases to search
field string Required

Field containing geospatial data to return
zoom number Required

Zoom level for the vector tile to search
x number Required

X coordinate for the vector tile to search
y number Required

Y coordinate for the vector tile to search

Query parameters

exact_bounds boolean

If false, the meta layer's feature is the bounding box of the tile. If true, the meta layer's feature is a bounding box resulting from a geo_bounds aggregation. The aggregation runs on values that intersect the // tile with wrap_longitude set to false. The resulting bounding box may be larger than the vector tile.
extent number

The size, in pixels, of a side of the tile. Vector tiles are square with equal sides.
grid_agg string

Aggregation used to create a grid for field.

Values are geotile or geohex.
grid_precision number

Additional zoom levels available through the aggs layer. For example, if is 7 and grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results don't include the aggs layer.
grid_type string

Determines the geometry type for features in the aggs layer. In the aggs layer, each feature represents a geotile_grid cell. If 'grid' each feature is a Polygon of the cells bounding box. If 'point' each feature is a Point that is the centroid of the cell.

Values are grid, point, or centroid.
size number

Maximum number of features to return in the hits layer. Accepts 0-10000. If 0, results don't include the hits layer.
with_labels boolean
If true, the hits and aggs layers will contain additional point features representing suggested label positions for the original features.
- Point and MultiPoint features will have one of the points selected.
- Polygon and MultiPolygon features will have a single point generated, either the centroid, if it is within the polygon, or another point within the polygon selected from the sorted triangle-tree.
- LineString features will likewise provide a roughly central point selected from the triangle-tree.
- The aggregation results will provide one central point for each aggregation bucket.
All attributes from the original features will also be copied to the new label features. In addition, the new features will be distinguishable using the tag _mvt_label_position.

application/json

Body

aggs object
Sub-aggregations for the geotile_grid.

It supports the following aggregation types:
- avg
- boxplot
- cardinality
- extended stats
- max
- median absolute deviation
- min
- percentile
- percentile-rank
- stats
- sum
- value count
The aggregation names can't start with _mvt_. The _mvt_ prefix is reserved for internal aggregations.
buffer number

The size, in pixels, of a clipping buffer outside the tile. This allows renderers to avoid outline artifacts from geometries that extend past the extent of the tile.
exact_bounds boolean

If false, the meta layer's feature is the bounding box of the tile. If true, the meta layer's feature is a bounding box resulting from a geo_bounds aggregation. The aggregation runs on values that intersect the <zoom>/<x>/<y> tile with wrap_longitude set to false. The resulting bounding box may be larger than the vector tile.
extent number

The size, in pixels, of a side of the tile. Vector tiles are square with equal sides.
fields string | array[string]
grid_agg string

Values are geotile or geohex.
grid_precision number

Additional zoom levels available through the aggs layer. For example, if <zoom> is 7 and grid_precision is 8, you can zoom in up to level 15. Accepts 0-8. If 0, results don't include the aggs layer.
grid_type string

Values are grid, point, or centroid.
query object

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

External documentation
runtime_mappings object
Hide runtime_mappings attribute Show runtime_mappings attribute object
- * object Additional properties
  Hide * attributes Show * attributes object
  
  fields object
  
  For type composite
  
  Hide fields attribute Show fields attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  
  fetch_fields array[object]
  
  For type lookup
  
  Hide fetch_fields attributes Show fetch_fields attributes object
  
  field string Required
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  format string
  
  format string
  
  A custom format for date type runtime fields.
  
  input_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_field string
  
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  
  target_index string
  
  script object
  
  Hide script attributes Show script attributes object
  
  source string | object
  
  One of:
  ScriptSource string ScriptSource object
  
  id string
  
  params object
  
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  
  Hide params attribute Show params attribute object
  
  * object Additional properties
  
  lang string
  
  Any of:
  ScriptLanguage string ScriptLanguage string
  
  Values are painless, expression, mustache, or java.
  
  options object
  
  Hide options attribute Show options attribute object
  
  * string Additional properties
  
  type string Required
  
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
size number

The maximum number of features to return in the hits layer. Accepts 0-10000. If 0, results don't include the hits layer.
sort string | object | array[string | object]
One of:
Field string SortOptions object Sort array[string | object]

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
Hide attributes Show attributes

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

Values are min, max, sum, avg, or median.

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

Values are in, ft, yd, mi, nmi, km, m, cm, or mm.

nested object

Hide nested attributes Show nested attributes object

filter object

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

External documentation

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

Hide script attributes Show script attributes object

source string | object

One of:
ScriptSource string ScriptSource object

id string

params object

Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

Hide params attribute Show params attribute object

* object Additional properties

lang string

Any of:
ScriptLanguage string ScriptLanguage string

Values are painless, expression, mustache, or java.

options object

Hide options attribute Show options attribute object

* string Additional properties

type string

Values are string, number, or version.

mode string

Values are min, max, sum, avg, or median.

nested object

Hide nested attributes Show nested attributes object

filter object

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

External documentation

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
One of:
Field string SortOptions object

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

Hide attributes Show attributes

_score object

Hide _score attribute Show _score attribute object

order string

Values are asc or desc.

_doc object

Hide _doc attribute Show _doc attribute object

order string

Values are asc or desc.

_geo_distance object

Hide _geo_distance attributes Show _geo_distance attributes object

mode string

Values are min, max, sum, avg, or median.

distance_type string

Values are arc or plane.

ignore_unmapped boolean

order string

Values are asc or desc.

unit string

Values are in, ft, yd, mi, nmi, km, m, cm, or mm.

nested object

Hide nested attributes Show nested attributes object

filter object

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

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

_script object

Hide _script attributes Show _script attributes object

order string

Values are asc or desc.

script object Required

Hide script attributes Show script attributes object

source

id string

params object

Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

lang

options object

type string

Values are string, number, or version.

mode string

Values are min, max, sum, avg, or median.

nested object

Hide nested attributes Show nested attributes object

filter object

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

max_children number

nested object

path string Required

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
track_total_hits boolean | number

Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
with_labels boolean
If true, the hits and aggs layers will contain additional point features representing suggested label positions for the original features.
- Point and MultiPoint features will have one of the points selected.
- Polygon and MultiPolygon features will have a single point generated, either the centroid, if it is within the polygon, or another point within the polygon selected from the sorted triangle-tree.
- LineString features will likewise provide a roughly central point selected from the triangle-tree.
- The aggregation results will provide one central point for each aggregation bucket.
All attributes from the original features will also be copied to the new label features. In addition, the new features will be distinguishable using the tag _mvt_label_position.

Responses

200 application/json

POST /{index}/_mvt/{field}/{zoom}/{x}/{y}

curl \
 --request POST 'http://api.example.com/{index}/_mvt/{field}/{zoom}/{x}/{y}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"grid_agg\": \"geotile\",\n  \"grid_precision\": 2,\n  \"fields\": [\n    \"name\",\n    \"price\"\n  ],\n  \"query\": {\n    \"term\": {\n      \"included\": true\n    }\n  },\n  \"aggs\": {\n    \"min_price\": {\n      \"min\": {\n        \"field\": \"price\"\n      }\n    },\n    \"max_price\": {\n      \"max\": {\n        \"field\": \"price\"\n      }\n    },\n    \"avg_price\": {\n      \"avg\": {\n        \"field\": \"price\"\n      }\n    }\n  }\n}"'

Request example

Run `GET museums/_mvt/location/13/4207/2692` to search an index for `location` values that intersect the `13/4207/2692` vector tile.

{
  "grid_agg": "geotile",
  "grid_precision": 2,
  "fields": [
    "name",
    "price"
  ],
  "query": {
    "term": {
      "included": true
    }
  },
  "aggs": {
    "min_price": {
      "min": {
        "field": "price"
      }
    },
    "max_price": {
      "max": {
        "field": "price"
      }
    },
    "avg_price": {
      "avg": {
        "field": "price"
      }
    }
  }
}

Response examples (200)

A successful response from `GET museums/_mvt/location/13/4207/2692`. It returns results as a binary vector tile. When decoded into JSON, the tile contains the following data.

{
  "hits": {
    "extent": 4096,
    "version": 2,
    "features": [
      {
        "geometry": {
          "type": "Point",
          "coordinates": [
            3208,
            3864
          ]
        },
        "properties": {
          "_id": "1",
          "_index": "museums",
          "name": "NEMO Science Museum",
          "price": 1750
        },
        "type": 1
      },
      {
        "geometry": {
          "type": "Point",
          "coordinates": [
            3429,
            3496
          ]
        },
        "properties": {
          "_id": "3",
          "_index": "museums",
          "name": "Nederlands Scheepvaartmuseum",
          "price": 1650
        },
        "type": 1
      },
      {
        "geometry": {
          "type": "Point",
          "coordinates": [
            3429,
            3496
          ]
        },
        "properties": {
          "_id": "4",
          "_index": "museums",
          "name": "Amsterdam Centre for Architecture",
          "price": 0
        },
        "type": 1
      }
    ]
  },
  "aggs": {
    "extent": 4096,
    "version": 2,
    "features": [
      {
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                3072,
                3072
              ],
              [
                4096,
                3072
              ],
              [
                4096,
                4096
              ],
              [
                3072,
                4096
              ],
              [
                3072,
                3072
              ]
            ]
          ]
        },
        "properties": {
          "_count": 3,
          "max_price.value": 1750.0,
          "min_price.value": 0.0,
          "avg_price.value": 1133.3333333333333
        },
        "type": 3
      }
    ]
  },
  "meta": {
    "extent": 4096,
    "version": 2,
    "features": [
      {
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                0,
                0
              ],
              [
                4096,
                0
              ],
              [
                4096,
                4096
              ],
              [
                0,
                4096
              ],
              [
                0,
                0
              ]
            ]
          ]
        },
        "properties": {
          "_shards.failed": 0,
          "_shards.skipped": 0,
          "_shards.successful": 1,
          "_shards.total": 1,
          "aggregations._count.avg": 3.0,
          "aggregations._count.count": 1,
          "aggregations._count.max": 3.0,
          "aggregations._count.min": 3.0,
          "aggregations._count.sum": 3.0,
          "aggregations.avg_price.avg": 1133.3333333333333,
          "aggregations.avg_price.count": 1,
          "aggregations.avg_price.max": 1133.3333333333333,
          "aggregations.avg_price.min": 1133.3333333333333,
          "aggregations.avg_price.sum": 1133.3333333333333,
          "aggregations.max_price.avg": 1750.0,
          "aggregations.max_price.count": 1,
          "aggregations.max_price.max": 1750.0,
          "aggregations.max_price.min": 1750.0,
          "aggregations.max_price.sum": 1750.0,
          "aggregations.min_price.avg": 0.0,
          "aggregations.min_price.count": 1,
          "aggregations.min_price.max": 0.0,
          "aggregations.min_price.min": 0.0,
          "aggregations.min_price.sum": 0.0,
          "hits.max_score": 0.0,
          "hits.total.relation": "eq",
          "hits.total.value": 3,
          "timed_out": false,
          "took": 2
        },
        "type": 3
      }
    ]
  }
}

Get the search shards

GET /_search_shards

Api key auth Basic auth Bearer auth

Get the indices and shards that a search request would be run against. This information can be useful for working out issues or planning optimizations with routing and shard preferences. When filtered aliases are used, the filter is returned as part of the indices section.

If the Elasticsearch security features are enabled, you must have the view_index_metadata or manage index privilege for the target data stream, index, or alias.

Query parameters

allow_no_indices boolean

If false, the request returns an error if any wildcard expression, index alias, or _all value targets only missing or closed indices. This behavior applies even if the request targets other open indices. For example, a request targeting foo*,bar* returns an error if an index starts with foo but no index starts with bar.
expand_wildcards string | array[string]

Type of index that wildcard patterns can match. If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams. Supports comma-separated values, such as open,hidden. Valid values are: all, open, closed, hidden, none.
ignore_unavailable boolean

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

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

The period to wait for a connection to the master node. If the master node is not available before the timeout expires, the request fails and returns an error. IT can also be set to -1 to indicate that the request should never timeout.
preference string

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

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

Responses

200 application/json
Hide response attributes Show response attributes object
- nodes object Required
  
  Hide nodes attribute Show nodes attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  name string Required
  
  ephemeral_id string Required
  
  transport_address string Required
  
  external_id string Required
  
  attributes object Required
  
  Lists node attributes.
  
  Hide attributes attribute Show attributes attribute object
  
  * string Additional properties
  
  roles array[string] Required
  
  @doc_id node-roles
  
  Values are master, data, data_cold, data_content, data_frozen, data_hot, data_warm, client, ingest, ml, voting_only, transform, remote_cluster_client, or coordinating_only.
  
  version string Required
  
  min_index_version number Required
  
  max_index_version number Required
- shards array[array] Required
  
  Hide shards attributes Show shards attributes object
  
  state string Required
  
  Values are UNASSIGNED, INITIALIZING, STARTED, or RELOCATING.
  
  primary boolean Required
  
  node string
  
  shard number Required
  
  index string Required
  
  allocation_id object
  
  Hide allocation_id attribute Show allocation_id attribute object
  
  * string
  
  recovery_source object
  
  Hide recovery_source attribute Show recovery_source attribute object
  
  * string
  
  unassigned_info object
  
  Hide unassigned_info attributes Show unassigned_info attributes object
  
  at string
  
  last_allocation_status string
  
  reason string Required
  
  Values are INDEX_CREATED, CLUSTER_RECOVERED, INDEX_REOPENED, DANGLING_INDEX_IMPORTED, NEW_INDEX_RESTORED, EXISTING_INDEX_RESTORED, REPLICA_ADDED, ALLOCATION_FAILED, NODE_LEFT, REROUTE_CANCELLED, REINITIALIZED, REALLOCATED_REPLICA, PRIMARY_FAILED, FORCED_EMPTY_PRIMARY, or MANUAL_ALLOCATION.
  
  details string
  
  failed_allocation_attempts number
  
  delayed boolean
  
  allocation_status string
  
  relocating_node string | null
  
  One of:
  NodeId string string-2 string | null
  
  relocation_failure_info object
  
  Hide relocation_failure_info attribute Show relocation_failure_info attribute object
  
  failed_attempts number Required
- indices object Required
  
  Hide indices attribute Show indices attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  aliases array[string]
  
  filter object
  
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  
  External documentation

GET /_search_shards

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

Response examples (200)

An abbreviated response from `GET /my-index-000001/_search_shards`.

{
  "nodes": {},
  "indices": {
      "my-index-000001": { }
  },
  "shards": [
      [
      {
          "index": "my-index-000001",
          "node": "JklnKbD7Tyqi9TP3_Q_tBg",
          "relocating_node": null,
          "primary": true,
          "shard": 0,
          "state": "STARTED",
          "allocation_id": {"id":"0TvkCyF7TAmM1wHP4a42-A"},
          "relocation_failure_info" : {
          "failed_attempts" : 0
          }
      }
      ],
      [
      {
          "index": "my-index-000001",
          "node": "JklnKbD7Tyqi9TP3_Q_tBg",
          "relocating_node": null,
          "primary": true,
          "shard": 1,
          "state": "STARTED",
          "allocation_id": {"id":"fMju3hd1QHWmWrIgFnI4Ww"},
          "relocation_failure_info" : {
          "failed_attempts" : 0
          }
      }
      ],
      [
      {
          "index": "my-index-000001",
          "node": "JklnKbD7Tyqi9TP3_Q_tBg",
          "relocating_node": null,
          "primary": true,
          "shard": 2,
          "state": "STARTED",
          "allocation_id": {"id":"Nwl0wbMBTHCWjEEbGYGapg"},
          "relocation_failure_info" : {
          "failed_attempts" : 0
          }
      }
      ],
      [
      {
          "index": "my-index-000001",
          "node": "JklnKbD7Tyqi9TP3_Q_tBg",
          "relocating_node": null,
          "primary": true,
          "shard": 3,
          "state": "STARTED",
          "allocation_id": {"id":"bU_KLGJISbW0RejwnwDPKw"},
          "relocation_failure_info" : {
          "failed_attempts" : 0
          }
      }
      ],
      [
      {
          "index": "my-index-000001",
          "node": "JklnKbD7Tyqi9TP3_Q_tBg",
          "relocating_node": null,
          "primary": true,
          "shard": 4,
          "state": "STARTED",
          "allocation_id": {"id":"DMs7_giNSwmdqVukF7UydA"},
          "relocation_failure_info" : {
          "failed_attempts" : 0
          }
      }
      ]
    ]
  }

Get anomaly detection jobs Added in 7.7.0

data.input_bytes number | string

model.bytes number | string

model.bytes_exceeded number | string

Get task information Technical preview

core string | null

max string | null

size string | null

keep_alive string | null

Update the connector pipeline Beta

Body Required

Create a data stream Added in 7.9.0

Get data stream lifecycle stats Added in 8.12.0

Body Required

source string | object

lang string

_source boolean | object

Delete an enrich policy Added in 7.5.0

Run multiple Fleet searches Technical preview

Body object Required

_source boolean | object

_source boolean | object

filter object | array[object]

filter object | array[object]

filter object | array[object]

filter object | array[object]

filter object | array[object]

source string | object

lang string

source string | object

lang string

Run multiple Fleet searches Technical preview

Body object Required

_source boolean | object

_source boolean | object

filter object | array[object]

filter object | array[object]

filter object | array[object]

filter object | array[object]

filter object | array[object]

source string | object

lang string

source string | object

lang string

Get index templates Added in 7.9.0

Body Required

source string | object

lang string

Resolve the cluster Added in 8.13.0

Create or update an alias Added in 1.3.0

Body Required

aliases string | array[string]

aliases string | array[string]

Validate a query Added in 1.3.0

Perform chat completion inference Added in 8.18.0

Body Required

content string | array[object]

tool_choice string | object

Perform completion inference on the service Added in 8.11.0

input string | array[string] Required

Delete an inference endpoint Added in 8.11.0