› › ›

ES|QL async query API

The async query API lets you asynchronously execute a query request, monitor its progress, and retrieve results when they become available.

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

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

const response = await client.transport.request({
  method: "POST",
  path: "/_query/async",
  body: {
    query:
      "\n    FROM library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
    wait_for_completion_timeout: "2s",
  },
});
console.log(response);

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

If the results are not available within the given timeout period, 2 seconds in this case, no results are returned but rather a response that includes:

A query ID
An is_running value of true, indicating the query is ongoing

The query continues to run in the background without blocking other requests.

{
  "id": "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
  "is_running": true
}

Otherwise, if the response’s is_running value is false, the async query has finished and the results are returned.

{
  "is_running": false,
  "columns": ...
}

Request

POST /_query/async

Prerequisites

If the Elasticsearch security features are enabled, you must have the read index privilege for the data stream, index, or alias you query.

Path parameters

The API accepts the same parameters as the synchronous query API.

Request body

The API accepts the same request body as the synchronous query API, along with the following parameters:

wait_for_completion_timeout

(Optional, time value) Timeout duration to wait for the request to finish. Defaults to a 1 second, meaning the request waits for 1 second for the query results.

If the query completes during this period then results will be returned. Otherwise, a query id is returned that can later be used to retrieve the results.

If the request does not complete during this period, a query id is returned.

keep_on_completion

(Optional, Boolean) If true, the query and its results are stored in the cluster.

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

keep_alive

(Optional, time value) Period for which the query and its results are stored in the cluster. Defaults to 5d (five days).

When this period expires, the query and its results are deleted, even if the query is still ongoing.

If the keep_on_completion parameter is false, Elasticsearch only stores async queries that do not complete within the period set by the wait_for_completion_timeout parameter, regardless of this value.

Response body

The API returns the same response body as the synchronous query API, along with the following properties:

id

(string) Identifier for the query.

This query ID is only provided if one of the following conditions is met:

A query request does not return complete results during the wait_for_completion_timeout parameter’s timeout period.
The query request’s keep_on_completion parameter is true.

You can use this ID with the ES|QL async query get API to get the current status and available results for the query.

is_running

(Boolean) If true, the query request is still executing.

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/esql-async-query-api.html