Get EQL search results

POST also GET /{index}/_eql/search

Returns search results for an Event Query Language (EQL) query. EQL assumes each document in a data stream or index corresponds to an event.

Read the reference documentation

Authentication

Api key

Authorization: <value>

Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:

		curl -X GET "${ES_URL}/_cat/indices?v=true" \
  -H "Authorization: ApiKey ${API_KEY}"

To get API keys, use the /_security/api_key APIs.

Basic

Authorization: Basic <credentials>

Bearer

Authorization: Bearer <token>

Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API. For examples, refer to Token-based authentication services

Query parameters

allow_no_indices boolean · default: true

Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes _all string or when no indices have been specified)

allow_partial_search_results boolean · default: false

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 · 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 true, missing or closed indices are not included in the response.

keep_alive string · 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

Timeout duration to wait for the request to finish. Defaults to no timeout, meaning the request waits for complete search results.

Reference

Request body

query string required: EQL query you wish to run.
case_sensitive boolean
event_category_field string · default: event.category: Field containing the event classification, such as process, file, or network.
tiebreaker_field string: Field used to sort hits with the same timestamp in ascending order
timestamp_field string · default: @timestamp: Field containing event timestamp.
fetch_size number · default: 1000: Maximum number of events to search at a time for sequence queries.
filter union oneOf: Query, written in Query DSL, used to filter the events on which the EQL query runs.; One of: Query[] or Query
keep_alive string
keep_on_completion boolean
wait_for_completion_timeout string
allow_partial_search_results boolean · default: true: 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: 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: For basic queries, the maximum number of matching events to return. Defaults to 10
fields union oneOf: Array of wildcard (*) patterns. The response returns values for field names matching these patterns in the fields property of each hit.; object or object[]
result_position enum · default: tail: 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 object
max_samples_per_key number · default: 1: 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.

Run POST /my-data-stream/_eql/search to search for a sequence of events. The sequence starts with an event with an event.category of file, a file.name of cmd.exe, and a process.pid other than 2013. It is followed by an event with an event.category of process and a process.executable that contains the substring regsvr32. These events must also share the same process.pid value.

Console Kibana Dev Tools

POST /my-data-stream/_eql/search
{
  "query": """
    sequence by process.pid
      [ file where file.name == "cmd.exe" and process.pid != 2013 ]
      [ process where stringContains(process.executable, "regsvr32") ]
  """
}

Generated from the API spec

curl Shell

curl -X POST "$ELASTICSEARCH_URL/my-data-stream/_eql/search" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": """
    sequence by process.pid
      [ file where file.name == "cmd.exe" and process.pid != 2013 ]
      [ process where stringContains(process.executable, "regsvr32") ]
  """
}'

Generated from the API spec

Response

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

Authentication

Path parameters

Query parameters

Request body { }

Response

Request body