elasticsearch/docs/reference/eql/get-async-eql-search-api.asciidoc

[role="xpack"]
[testenv="basic"]

[[get-async-eql-search-api]]
=== Get async EQL search API
++++
<titleabbrev>Get async EQL search</titleabbrev>
++++

Returns the current status and available results for an <<eql-search-async,async
EQL search>> or a <<eql-search-store-sync-eql-search,stored synchronous EQL
search>>.

[source,console]
----
GET /_eql/search/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=
----
// TEST[skip: no access to search ID]

[[get-async-eql-search-api-request]]
==== {api-request-title}

`GET /_eql/search/<search_id>`

[[get-async-eql-search-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, only the user who first submitted
the EQL search can retrieve the search using this API.

* See <<eql-required-fields>>.

[[get-async-eql-search-api-limitations]]
===== Limitations

See <<eql-syntax-limitations,EQL limitations>>.

[[get-async-eql-search-api-path-params]]
==== {api-path-parms-title}

`<search_id>`::
(Required, string)
Identifier for the search.
+
A search ID is provided in the <<eql-search-api,EQL search API>>'s response for
an <<eql-search-async,async search>>. A search ID is also provided if the
request's <<eql-search-api-keep-on-completion,`keep_on_completion`>> parameter
is `true`.

[[get-async-eql-search-api-query-params]]
==== {api-query-parms-title}

`keep_alive`::
(Optional, <<time-units,time value>>)
Period for which the search and its results are stored on the cluster. Defaults
to the `keep_alive` value set by the search's <<eql-search-api,EQL search
API>> request.
+
If specified, this parameter sets a new `keep_alive` period for the search,
starting when the get async EQL search API request executes. This new period
overwrites the one specified in the EQL search API request.
+
When this period expires, the search and its results are deleted, even if the
search is ongoing.

`wait_for_completion_timeout`::
(Optional, <<time-units,time value>>)
Timeout duration to wait for the request to finish. Defaults to no timeout,
meaning the request waits for complete search results.
+
If this parameter is specified and the request completes during this period,
complete search results are returned.
+
If the request does not complete during this period, the response returns an
`is_partial` value of `true` and no search results.

[role="child_attributes"]
[[get-async-eql-search-api-response-body]]
==== {api-response-body-title}

The async EQL search API returns the same response body as the EQL search API.
See the EQL search API's <<eql-search-api-response-body,response body
parameters>>.