Type to search.

Run an async search

  • POST /{index}/_async_search
  • POST /_async_search
Auth The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 7.7 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

When the primary sort of the results is an indexed field, shards get sorted based on minimum and maximum value that they hold for that field. Partial results become available following the sort criteria that was requested.

Warning

Asynchronous search does not support scroll or search requests that include only the suggest section.

By default, Elasticsearch does not allow you to store an async search response larger than 10Mb and an attempt to do this results in an error. The maximum allowed size for a stored async search response can be set by changing the search.max_async_search_response_size cluster level setting.

Required privileges

Index privileges read

Path parameters

index union string | string[] optional

A comma-separated list of index names to search; use _all or empty string to perform the operation on all indices

Leave it out to use /_async_search.

Query parameters

wait_for_completion_timeout string · default: 1s

Blocks and waits until the search is completed up to a certain timeout. When the async search completes within the timeout, the response won’t include the ID as the results are not stored in the cluster.

keep_alive string · default: 5d

Specifies how long the async search needs to be available. Ongoing async searches and any saved search results are deleted after this period.

keep_on_completion boolean · default: false

If true, results are stored for later retrieval when the search completes within the wait_for_completion_timeout.

allow_no_indices boolean

A setting that does two separate checks on the index expression. If false, the request returns an error (1) if any wildcard expression (including _all and *) resolves to zero matching indices or (2) if the complete set of resolved indices, aliases or data streams is empty after all expressions are evaluated. If true, index expressions that resolve to no indices are allowed and the request returns an empty result.

allow_partial_search_results boolean · default: true

Indicate if an error should be returned if there is a partial search failure or timeout

analyzer string

The analyzer to use for the query string

analyze_wildcard boolean · default: false

Specify whether wildcard and prefix queries should be analyzed

batched_reduce_size number · default: 5

Affects how often partial results become available, which happens whenever shard results are reduced. A partial reduction is performed every time the coordinating node has received a certain number of new shard responses (5 by default).

ccs_minimize_roundtrips boolean · default: false

The default value is the only supported value.

default_operator enum · default: or

The default operator for query string query (AND or OR)

Values: and AND or OR
df string

The field to use as default where no field prefix is given in the query string

docvalue_fields union string | string[]

A comma-separated list of fields to return as the docvalue representation of a field for each hit

expand_wildcards union oneOf · default: open

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

Supported values include:

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

Specify whether to return detailed information about score computation as part of a hit

ignore_throttled boolean

Whether specified concrete, expanded or aliased indices should be ignored when throttled

ignore_unavailable boolean

If false, the request returns an error if it targets a concrete (non-wildcarded) index, alias, or data stream that is missing, closed, or otherwise unavailable. If true, unavailable concrete targets are silently ignored.

lenient boolean

Specify whether format-based query failures (such as providing text to a numeric field) should be ignored

max_concurrent_shard_requests number · default: 5

The number of concurrent shard requests per node this search executes 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 · default: random

Specify the node or shard the operation should be performed on

request_cache boolean · default: true

Specify if request cache should be used for this request or not, defaults to true

routing union string | string[]

A comma-separated list of specific routing values

search_type enum

Search operation type

Supported values include:

  • query_then_fetch: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate.
  • dfs_query_then_fetch: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate.
Values: query_then_fetch dfs_query_then_fetch
stats string[]

Specific 'tag' of the request for logging and statistical purposes

stored_fields union string | string[]

A comma-separated list of stored fields to return as part of a hit

suggest_field string

Specifies which field to use for suggestions.

suggest_mode enum · default: missing

Specify suggest mode

Supported values include:

  • missing: Only generate suggestions for terms that are not in the shard.
  • popular: Only suggest terms that occur in more docs on the shard than the original term.
  • always: Suggest any matching suggestions based on terms in the suggest text.
Values: missing popular always
suggest_size number

How many suggestions to return in response

suggest_text string

The source text for which the suggestions should be returned.

terminate_after number

The maximum number of documents to collect for each shard, upon reaching which the query execution will terminate early

timeout string

Explicit operation timeout

Reference
track_total_hits boolean | number

Indicate if the number of documents that match the query should be tracked. A number can also be specified, to accurately track the total hit count up to the number.

track_scores boolean

Whether to calculate and return scores even if they are not used for sorting

typed_keys boolean

Specify whether aggregation and suggester names should be prefixed by their respective types in the response

rest_total_hits_as_int boolean · default: false

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

version boolean

Specify whether to return document version as part of a hit

_source union oneOf

True or false to return the _source field or not, or a list of fields to return

One of: boolean or string
_source_excludes union string | string[]

A list of fields to exclude from the returned _source field

_source_includes union string | string[]

A list of fields to extract and return from the _source field

seq_no_primary_term boolean

Specify whether to return sequence number and primary term of the last modification of each hit

q string

Query in the Lucene query string syntax

size number · default: 10

Number of hits to return

from number · default: 0

Starting offset

sort union string | string[]

A comma-separated list of

Request body

aggregations map string to {} Aggregation
explain boolean · default: false

If true, returns detailed information about score computation as part of a hit.

ext map string to object

Configuration of search extensions defined by Elasticsearch plugins.

from number · default: 0

Starting document offset. 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
Same fields as highlight in inner_hits
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 string to number[]

Boosts the _score of documents from specified indices.

min_score number

Minimum _score for matching documents. Documents with a lower _score are not included in search results and results collected by aggregations.

post_filter {} Query
profile boolean
query {} Query

Defines the search definition using the Query DSL.

script_fields map string to object

Retrieve a script evaluation (based on different fields) for each hit.

search_after union[]
size number · default: 10

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.

sort union oneOf
Same options as sort in inner_hits
_source union oneOf

Indicates which source fields are returned for matching documents. These fields are returned in the hits._source property of the search response.

One of:
terminate_after number · default: 0

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. Defaults to 0, which does not terminate query execution early.

timeout string

Specifies 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 · default: false

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

version boolean · default: false

If true, returns document version as part of a hit.

seq_no_primary_term boolean

If true, returns sequence number and primary term of the last modification of each hit. See Optimistic concurrency control.

stored_fields union oneOf

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.

One of: string[] or string
runtime_mappings object

Defines one or more runtime fields in the search request. These fields take precedence over mapped fields with the same name.

stats string[]

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

application/json
id string
is_partial boolean required

When the query is no longer running, this property indicates whether the search failed or was successfully completed on all shards. While the query is running, is_partial is always set to true.

is_running boolean required

Indicates whether the search is still running or has completed.

Note

If the search failed after some shards returned their results or the node that is coordinating the async search dies, results may be partial even though is_running is false.

expiration_time union oneOf

Indicates when the async search will expire.

One of: string or number
expiration_time_in_millis number required
start_time union oneOf
One of: string or number
start_time_in_millis number required
completion_time union oneOf

Indicates when the async search completed. It is present only when the search has completed.

One of: string or number
completion_time_in_millis number
response object required
aggregations map string to {} Aggregation result

Partial aggregations results, coming from the shards that have already completed running the query.

fields map string to object
hits object required
total union oneOf

Total hit count information, present only if track_total_hits wasn't false in the search request.

One of:
relation enum required

Supported values include:

  • eq: Accurate
  • gte: Lower bound, including returned events or sequences
Values: eq gte
value number required
hits object[] required
_index string required
_id string
_score union number | string nullable
fields map string to object
highlight map string to string
inner_hits map string to object
matched_queries union oneOf
One of: string[] or string to number
_ignored string[]
ignored_field_values map string to object
_shard string
_node string
_routing string
_source object
_rank number
_seq_no number
_primary_term number
_version number
sort union[]
max_score union number | string nullable
max_score number
num_reduce_phases number

Indicates how many reductions of the results have been performed. If this number increases compared to the last retrieved results for a get asynch search request, you can expect additional results included in the search response.

pit_id string
_scroll_id string
_shards object required

Indicates how many shards have run the query. Note that in order for shard results to be included in the search response, they need to be reduced first.

Same fields as _shards in details
suggest map string to oneOf
terminated_early boolean
timed_out boolean required
took number required