--- type: api title: Get EQL search results description: **All methods and paths for this operation:** url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-eql-search resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-eql-search products: - Elasticsearch --- # Get EQL search results Availability: 7.9+ ## Paths - `POST` (also `GET`) `/{index}/_eql/search` - [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#apikeyauth) - [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#basicauth) - [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#bearerauth) #### Path Parameters - `index` (union IndexName | [] IndexName) Comma-separated list of index names to scope the operation ## Description Returns search results for an Event Query Language (EQL) query. EQL assumes each document in a data stream or index corresponds to an event. [Learn more about EQL](https://www.elastic.co/docs/explore-analyze/query-filter/languages/eql) ## Query String Parameters - `allow_no_indices` (boolean · default: true) 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) If true, returns partial results if there are shard failures. If false, returns an error with no partial results. - `allow_partial_sequence_results` (boolean · default: false) If true, sequence queries will return partial results in case of shard failures. If false, they will return no results at all. This flag has effect only if allow_partial_search_results is true. - `expand_wildcards` (string ExpandWildcards · 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` - `ccs_minimize_roundtrips` (boolean · default: true) Indicates whether network round-trips should be minimized as part of cross-cluster search requests execution - `ignore_unavailable` (boolean · default: true) 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. - `keep_alive` (string Duration · default: 5d) Period for which the search and its results are stored on the cluster. - `keep_on_completion` (boolean · default: false) If true, the search and its results are stored on the cluster. - `wait_for_completion_timeout` (string Duration) Timeout duration to wait for the request to finish. Defaults to no timeout, meaning the request waits for complete search results. ## Request Body `application/json` - `query` (string) — required EQL query you wish to run. - `case_sensitive` (boolean) — optional - `event_category_field` (string Field · default: event.category) — optional Field containing the event classification, such as process, file, or network. - `tiebreaker_field` (string Field) — optional Field used to sort hits with the same timestamp in ascending order - `timestamp_field` (string Field · default: @timestamp) — optional Field containing event timestamp. - `fetch_size` (number uint · default: 1000) — optional Maximum number of events to search at a time for sequence queries. - `filter` (union oneOf) — optional Query, written in Query DSL, used to filter the events on which the EQL query runs. One of: [`QueryContainer[]`](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer) or [`QueryContainer`](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer) See [QueryContainer](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/types/_types-query_dsl-querycontainer) - `keep_alive` (string Duration) — optional - `keep_on_completion` (boolean) — optional - `wait_for_completion_timeout` (string Duration) — optional - `allow_partial_search_results` (boolean · default: true) — optional Allow query execution also in case of shard failures. If true, the query will keep running and will return results based on the available shards. For sequences, the behavior can be further refined using allow_partial_sequence_results - `allow_partial_sequence_results` (boolean · default: false) — optional This flag applies only to sequences and has effect only if allow_partial_search_results=true. If true, the sequence query will return results based on the available shards, ignoring the others. If false, the sequence query will return successfully, but will always have empty results. - `size` (number uint) — optional For basic queries, the maximum number of matching events to return. Defaults to 10 - `fields` (union oneOf) — optional Array of wildcard (*) patterns. The response returns values for field names matching these patterns in the fields property of each hit. `FieldAndFormat` or `FieldAndFormat[]` - `field` (string Field) — required A wildcard pattern. The request returns values for field names matching this pattern. - `format` (string) — optional The format in which the values are returned. - `include_unmapped` (boolean) — optional - `result_position` (enum ResultPosition · default: tail) — optional Supported values include: - `tail`: Return the most recent matches, similar to the Unix tail command. - `head`: Return the earliest matches, similar to the Unix head command. Values: `tail`, `head` - `runtime_mappings` (RuntimeFields) — optional - `max_samples_per_key` (number · default: 1) — optional By default, the response of a sample query contains up to `10` samples, with one sample per unique set of join keys. Use the `size` parameter to get a smaller or larger set of samples. To retrieve more than one sample per set of join keys, use the `max_samples_per_key` parameter. Pipes are not supported for sample queries. ## Response `application/json` - `id` (string Id) Identifier for the search. - `is_partial` (boolean) If true, the response does not contain complete search results. - `is_running` (boolean) If true, the search request is still executing. - `took` (DurationValueUnitMillis) Milliseconds it took Elasticsearch to execute the request. - `timed_out` (boolean) If true, the request timed out before completion. - `hits` ({} EqlHits) Contains matching events and sequences. Also contains related metadata. - `total` ({} TotalHits) Metadata about the number of matching events or sequences. - `relation` (enum TotalHitsRelation) Supported values include: - `eq`: Accurate - `gte`: Lower bound, including returned events or sequences Values: `eq`, `gte` - `value` (number) - `events` ([] HitsEvent) Contains events matching the query. Each object represents a matching event. - `_index` (string IndexName) Name of the index containing the event. - `_id` (string Id) Unique identifier for the event. This ID is only unique within the index. - `_source` (object) Original JSON body passed for the event at index time. - `missing` (boolean) Set to `true` for events in a timespan-constrained sequence that do not meet a given condition. - `fields` (map string to object) - `sequences` ([] HitsSequence) Contains event sequences matching the query. Each object represents a matching sequence. This parameter is only returned for EQL queries containing a sequence. - `events` ([] HitsEvent) Contains events matching the query. Each object represents a matching event. - `_index` (string IndexName) Name of the index containing the event. - `_id` (string Id) Unique identifier for the event. This ID is only unique within the index. - `_source` (object) Original JSON body passed for the event at index time. - `missing` (boolean) Set to `true` for events in a timespan-constrained sequence that do not meet a given condition. - `fields` (map string to object) - `join_keys` ([] object) Shared field values used to constrain matches in the sequence. These are defined using the by keyword in the EQL query syntax. - `shard_failures` ([] ShardFailure) Contains information about shard failures (if any), in case allow_partial_search_results=true - `index` (string IndexName) - `node` (string) - `reason` ({} ErrorCause) - `type` (string) The type of error - `reason` (union string) — nullable A human-readable explanation of the error, in English. One of: `string` - `stack_trace` (string) The server stack trace. Present only if the `error_trace=true` parameter was sent with the request. - `caused_by` ({} ErrorCause) — recursive Same fields as `reason` in `shard_failures` - `root_cause` ([] ErrorCause) — recursive Same fields as `reason` in `shard_failures` - `suppressed` ([] ErrorCause) — recursive Same fields as `reason` in `shard_failures` - `shard` (number) - `status` (string) - `primary` (boolean) ## Code Examples #### Console ```console POST /my-data-stream/_eql/search { "query": """ process where (process.name == "cmd.exe" and process.pid != 2013) """ } ``` #### JavaScript ```javascript const response = await client.eql.search({ index: "my-data-stream", query: '\n process where (process.name == "cmd.exe" and process.pid != 2013)\n ', }); ``` #### Python ```python resp = client.eql.search( index="my-data-stream", query="\n process where (process.name == \"cmd.exe\" and process.pid != 2013)\n ", ) ``` #### curl ```curl curl -X POST "$ELASTICSEARCH_URL/my-data-stream/_eql/search" \ -H "Authorization: ApiKey $ELASTIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "\n process where (process.name == \u0022cmd.exe\u0022 and process.pid != 2013)\n " }' ``` #### Java ```java client.eql().search(s -> s .index("my-data-stream") .query(""" process where (process.name == "cmd.exe" and process.pid != 2013) """) ); ``` #### C# ```c# var response = await client.Eql .SearchAsync(indices: new[] { "my-data-stream" }, d1 => d1 .Query("\n process where (process.name == \"cmd.exe\" and process.pid != 2013)\n ") ); ``` #### PHP ```php $resp = $client->eql()->search([ "index" => "my-data-stream", "body" => [ "query" => "\n process where (process.name == \"cmd.exe\" and process.pid != 2013)\n ", ], ]); ``` #### Ruby ```ruby response = client.eql.search( index: "my-data-stream", body: { "query": "\n process where (process.name == \"cmd.exe\" and process.pid != 2013)\n " } ) ``` ## Response Examples #### A successful response for performing search with an EQL query. ```json { "is_partial": false, "is_running": false, "took": 6, "timed_out": false, "hits": { "total": { "value": 1, "relation": "eq" }, "sequences": [ { "join_keys": [ 2012 ], "events": [ { "_index": ".ds-my-data-stream-2099.12.07-000001", "_id": "AtOJ4UjUBAAx3XR5kcCM", "_source": { "@timestamp": "2099-12-06T11:04:07.000Z", "event": { "category": "file", "id": "dGCHwoeS", "sequence": 2 }, "file": { "accessed": "2099-12-07T11:07:08.000Z", "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe", "type": "file", "size": 16384 }, "process": { "pid": 2012, "name": "cmd.exe", "executable": "C:\\Windows\\System32\\cmd.exe" } } }, { "_index": ".ds-my-data-stream-2099.12.07-000001", "_id": "OQmfCaduce8zoHT93o4H", "_source": { "@timestamp": "2099-12-07T11:07:09.000Z", "event": { "category": "process", "id": "aR3NWVOs", "sequence": 4 }, "process": { "pid": 2012, "name": "regsvr32.exe", "command_line": "regsvr32.exe /s /u /i:https://...RegSvr32.sct scrobj.dll", "executable": "C:\\Windows\\System32\\regsvr32.exe" } } } ] } ] } } ```