Query

Query Data

Given a search query, fetch all matching results, up to the maximum number requested, or the maximum that the backend data server will provide.

Query Structure

The query structure resembles the following:

(field_name1:required_value AND field_name2:>50) OR field_name3:"some string value" | groupby field_name1 field_name2 | sortby field_name1 field_name3 | ...

Everything the left of the | "pipe" character must be in Lucene syntax.

The operation keywords, such as AND, OR, NOT must always be capitalized.

For more information on the query syntax, refer to the Security Onion documentation and search for OQL.

get/connect/events/

Query parameters

querystring required

User defined search query

rangestring required

Date range, in the specified timezone

zonestring required

Timezone of the date range

formatstring required

Date range date format. Use the example, exactly as shown, if not familiar with date formats

metricLimitinteger required

Maximum number of metrics to include in each aggregation

eventLimitinteger required

Maximum number of events to return

Response

Outputs the list of search results

completeTimestring

The date and time when the search completed

createTimestring

The date and time when the search was submitted

elapsedMsinteger

The number of milliseconds it took to complete the search

errorsstring[]

A list of errors that the search encountered. The presence of errors does not necessarily preclude the search from returning events."

metricsobject

The collection of aggregated metrics associated with this search

totalEventsinteger

The total number of matching events (not necessarily the total number returned)

Example response

[
  {
    "completeTime": "2024-12-04T19:54:33.822293482Z",
    "createTime": "2024-12-04T19:54:33.519514906Z",
    "criteria": {
      "beginTime": "2024-12-03T14:31:35-05:00",
      "createTime": "2024-12-04T19:31:42.73865332Z",
      "endTime": "2024-12-04T14:31:35-05:00",
      "eventLimit": 100,
      "metricLimit": 10,
      "query": "(*) AND tags:alert AND NOT event.acknowledged:true AND NOT event.escalated:true | groupby rule.name event.module* event.severity_label rule.uuid"
    },
    "elapsedMs": 299,
    "errors": [
      "all shards failed"
    ],
    "events": [
      {
        "id": "ru5Jk5MB4OVrR03M8ee8",
        "payload": {
          "@timestamp": "2024-12-04T20:06:04.725Z",
          "@version": "1",
          "client.ip": "4.33.51.1",
          "client.port": "5544"
        },
        "sort": [
          "0:33.32.12.56"
        ],
        "source": "so:.ds-logs-zeek-so-2024.11.21-000017",
        "time": "2024-12-04T20:08:15.97Z",
        "timestamp": "2024-12-04T20:08:15.970Z"
      }
    ],
    "totalEvents": 5109848
  }
]

Changes

Changed in 3 of the 23 revisions of this API.37

Aug 25, 20254e3bdeaab6cb3See the full diff
- ●
  removed the optional property items/criteria/parsedQuery from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property items/criteria/searchAfter from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property items/criteria/sortFields from the response with the 200 status
  response-optional-property-removed
This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jan 15, 20250600bede2a742See the full diff
- ○
  api tag Query added
  api-tag-added
- ○
  api tag Events removed
  api-tag-removed
Dec 10, 2024ee1120fd1e205See the full diff
- ○
  api tag Events added
  api-tag-added
- ○
  api tag Query removed
  api-tag-removed
- ○
  added the optional property items/criteria/parsedQuery to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/criteria/searchAfter to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/criteria/sortFields to the response with the 200 status
  response-optional-property-added
This revision also has 35 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history