Event query API

The event query service provides resources for getting, searching, and counting events, and for getting event frequency over time. To update the status or annotations of an existing event, use the event management service.

Resource list

The event query service provides the following resources:

Get an event (GET /v1/events/{id})
Search events (POST /v1/events:search)
Count events (POST /v1/events:count)
Get event frequency (POST /v1/events:frequency)

Get an event

GET /v1/events/{id}

Get one event by its ID.

Request parameters

The following table describes the path and query parameters for a request to get an event:

Field	Type	Required	Description
`occurrenceIds`	string	No	A query parameter that specifies one or more occurrence IDs. When you omit this parameter, the most recent occurrence is returned. To request more than one occurrence, repeat the parameter, for example: `?occurrenceIds=occ1&occurrenceIds=occ2`.
`fields`	string	No	A query parameter that specifies the name of a field to include in the response. When you omit this parameter, all fields are returned. To request more than one field, repeat the parameter.
`id`	string	Yes	A path parameter that specifies the ID of the event to get.

Response codes

Code	Description
200	The request was processed successfully. For operations on multiple objects, check the response body for per-item results.
400	The request couldn't be processed. The request body is missing, malformed, or contains invalid values.
401	Authentication failed. The API key is missing or invalid.
500	An unexpected error occurred. Try the request again. If the problem persists, contact Virtana support.

Request example

curl https://YOUR-API-ENDPOINT/v1/events/AAAABWRDWOPER3lzOFI2tSCG49g= \
  -H "zenoss-api-key: YOUR-API-KEY"

Response example

{
  "result": {
    "id": "AAAABWRDWOPER3lzOFI2tSCG49g=",
    "entity": "/entities/example-host-01",
    "name": "high-cpu",
    "count": 1,
    "occurrences": [
      {
        "id": "9f3a2c1d-7e4b-4a9f-8d2e-1b5c6f0e3a7d",
        "eventId": "AAAABWRDWOPER3lzOFI2tSCG49g=",
        "severity": "SEVERITY_ERROR",
        "status": "STATUS_OPEN",
        "summary": "CPU usage exceeded 90% for 5 minutes",
        "startTime": "1748000000000",
        "lastSeen": "1748003600000"
      }
    ]
  }
}

Search events

POST /v1/events:search

Search for events by filter, time range, severity, and status. The results support sorting and pagination.

Request template

An abstract preview of a JSON request to search for events.

{
  "query": {
    "timeRange": {
      "start": <ms-since-epoch>,
      "end": <ms-since-epoch>
    },
    "clause": {
      "filter": {
        "field": "<field-name>",
        "operation": "<operation>",
        "value": "<value>"
      }
    },
    "severities": ["<severity>"],
    "statuses": ["<status>"],
    "sortBy": [
      { "byField": { "field": "<field-name>", "order": "<sort-order>" } }
    ],
    "pageInput": {
      "limit": <integer>,
      "cursor": "<cursor>",
      "direction": "<direction>"
    },
    "activeCriteria": "<active-criteria>",
    "fields": [
      { "field": "<field-name>" }
    ]
  }
}

Request fields

The following table describes the fields in a request to search for events:

Field	Type	Required	Description
`query`	object	Yes	The search criteria.
`query.timeRange`	object	No	The time range to search.
`query.timeRange.start`	integer	No	The start of the time range, specified as milliseconds since the epoch (January 1, 1970 at 00:00:00 UTC).
`query.timeRange.end`	integer	No	The end of the time range, specified as milliseconds since the epoch (January 1, 1970 at 00:00:00 UTC).
`query.clause`	object	No	A filter clause to apply to event fields. To combine clauses, nest them with the `and`, `or`, and `not` combinators. The following are examples of each clause type: Simple filter: `{ "filter": { "field": "summary", "operation": "OP_CONTAINS", "value": "timeout" } }` Combined filter: `{ "and": { "clauses": [ { "filter": {...} }, { "filter": {...} } ] } }` Supported values for `operation`: `OP_EQUALS`, `OP_NOT_EQUALS`, `OP_CONTAINS`, `OP_NOT_CONTAINS`, `OP_STARTS_WITH`, `OP_END_WITH`, `OP_LESS`, `OP_GREATER`, `OP_LESS_OR_EQ`, `OP_GREATER_OR_EQ`, `OP_IN`, `OP_NOT_IN`, `OP_REGEX`, `OP_WILDCARD`, and `OP_EXISTS`.
`query.severities`	array	No	The event severities to match. When you specify more than one value, events that match any of the values are returned. Accepted values: `SEVERITY_DEFAULT`: Unknown. `SEVERITY_DEBUG`: By default, not severe enough to display in an events console. `SEVERITY_INFO`: Most likely, no action is required. `SEVERITY_WARNING`: Action may be required in the future. `SEVERITY_ERROR`: Entity is degraded but not down. `SEVERITY_CRITICAL`: Entity is down.
`query.statuses`	array	No	The event statuses to match. When you specify more than one value, events that match any of the values are returned. Accepted values: `STATUS_DEFAULT`: Unknown. `STATUS_OPEN`: Known to be in progress. `STATUS_SUPPRESSED`: Most likely ended. `STATUS_CLOSED`: Known to be ended.
`query.sortBy`	array	No	The sort criteria. Criteria are applied in order of decreasing priority.
`query.sortBy.byField`	object	No	Sorts results by the value of a field.
`query.sortBy.byField.field`	string	No	The name of the field to sort by, for example, `lastSeen`.
`query.sortBy.byField.order`	string	No	The sort order. Accepted values: `SORT_ORDER_ASC`: Ascending. `SORT_ORDER_DESC`: Descending.
`query.pageInput`	object	No	The pagination controls.
`query.pageInput.limit`	integer	No	The maximum number of results to return per page. When you omit this field, a system-defined limit applies.
`query.pageInput.cursor`	string	No	The pagination cursor. To get the next page, use the `pageInfo.endCursor` value from the previous response. To get the previous page, use the `pageInfo.startCursor` value.
`query.pageInput.direction`	string	No	The pagination direction. Default: `DIRECTION_FORWARD`. Accepted values: `DIRECTION_FORWARD`: Get the next page. `DIRECTION_BACKWARD`: Get the previous page.
`query.activeCriteria`	string	No	Determines which occurrences are considered active within the time range. Default: `BY_TIMERANGE`. Accepted values: `BY_TIMERANGE`: Occurrences last updated within the time range. `BY_OCCURRENCES`: Occurrences whose interval overlaps the time range.
`query.fields`	array	No	The fields to include in each result. When you omit this field, all fields are returned.
`query.fields.field`	string	No	The name of a field to include, for example, `eventClass`.

Response codes

Code	Description
200	The request was processed successfully. For operations on multiple objects, check the response body for per-item results.
400	The request couldn't be processed. The request body is missing, malformed, or contains invalid values.
401	Authentication failed. The API key is missing or invalid.
500	An unexpected error occurred. Try the request again. If the problem persists, contact Virtana support.

Request example

curl https://YOUR-API-ENDPOINT/v1/events:search \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s -S -d \
'{
  "query": {
    "timeRange": {
      "start": "1748000000000",
      "end":   "1748003600000"
    },
    "clause": {
      "filter": {
        "field": "source-type",
        "operation": "OP_EQUALS",
        "value": "cz"
      }
    },
    "severities": ["SEVERITY_ERROR", "SEVERITY_CRITICAL"],
    "statuses": ["STATUS_OPEN"],
    "fields": [
      { "field": "eventClass" }
    ],
    "sortBy": [
      { "byField": { "field": "lastSeen", "order": "SORT_ORDER_DESC" } }
    ],
    "pageInput": { "limit": 25 }
  }
}'

Response example

{
  "results": [
    {
      "id": "AAAABWRDWOPER3lzOFI2tSCG49g=",
      "entityName": "example-host-01",
      "name": "high-cpu",
      "occurrences": [
        {
          "id": "9f3a2c1d-7e4b-4a9f-8d2e-1b5c6f0e3a7d",
          "instanceCount": 1,
          "severity": "SEVERITY_ERROR",
          "status": "STATUS_OPEN",
          "summary": "CPU usage exceeded 90% for 5 minutes",
          "lastSeen": "1748003600000",
          "coreProperties": {
            "eventClass": ["/Perf/CPU"]
          }
        }
      ]
    }
  ],
  "pageInfo": {
    "count": "1",
    "totalCount": "1",
    "hasNext": false,
    "hasPrev": false,
    "endCursor": "eyJpZCI6IkFBQUFCV..."
  }
}

Count events

POST /v1/events:count

Count the events that match a query. You can group the counts by the values of one or more fields.

Request template

An abstract preview of a JSON request to count events.

{
  "query": { ... },
  "fields": [
    { "field": "<group-by-field>" }
  ],
  "countInstances": <boolean>
}

Request fields

The following table describes the fields in a request to count events:

Field	Type	Required	Description
`query`	object	No	The search criteria. When you omit this field, all events are counted. This field uses the same structure as the `query` field of the search events resource.
`fields`	array	No	The fields to group the counts by. When you omit this field, a single total count is returned.
`fields.field`	string	No	The name of a field to group by, for example, `severity`. Required when you specify `fields`.
`countInstances`	boolean	No	Count individual occurrence instances (`true`) or distinct events (`false`). Default: `false`.

Response codes

Code	Description
200	The request was processed successfully. For operations on multiple objects, check the response body for per-item results.
400	The request couldn't be processed. The request body is missing, malformed, or contains invalid values.
401	Authentication failed. The API key is missing or invalid.
500	An unexpected error occurred. Try the request again. If the problem persists, contact Virtana support.

Request example

curl https://YOUR-API-ENDPOINT/v1/events:count \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s -S -d \
'{
  "query": {
    "timeRange": {
      "start": "1748000000000",
      "end":   "1748003600000"
    },
    "statuses": ["STATUS_OPEN"]
  },
  "fields": [
    { "field": "severity" }
  ]
}'

Response example

{
  "results": {
    "severity": {
      "values": [
        { "value": 3, "count": "32" },
        { "value": 4, "count": "17" },
        { "value": 5, "count": "4"  }
      ]
    }
  }
}

Note

The event query service returns grouped field values in the results object as integers, not as enumeration names. Use the following mappings to interpret them:

severity: 0 is SEVERITY_DEFAULT, 1 is SEVERITY_DEBUG, 2 is SEVERITY_INFO, 3 is SEVERITY_WARNING, 4 is SEVERITY_ERROR, and 5 is SEVERITY_CRITICAL.
status: 0 is STATUS_DEFAULT, 1 is STATUS_OPEN, 2 is STATUS_SUPPRESSED, and 3 is STATUS_CLOSED.

Get event frequency

POST /v1/events:frequency

Get a time series of event counts over the time range of a query. You can group the time series by field values and combine the counts into larger time intervals.

Request template

An abstract preview of a JSON request to get event frequency.

{
  "query": { ... },
  "fields": [
    { "field": "<field-name>" }
  ],
  "groupBy": [
    { "field": "<group-by-field>" }
  ],
  "downsample": <milliseconds>,
  "countInstances": <boolean>
}

Request fields

The following table describes the fields in a request to get event frequency:

Field	Type	Required	Description
`query`	object	Yes	The search criteria. This field uses the same structure as the `query` field of the search events resource.
`query.timeRange`	object	Yes	The time range of the time series. Event frequency requests always require a time range.
`fields`	array	Yes	The fields to include in the results.
`fields.field`	string	Yes	The name of a field to include, for example, `severity`.
`groupBy`	array	Yes	The fields to group the time series by.
`groupBy.field`	string	Yes	The name of a field to group by, for example, `severity`.
`downsample`	integer	No	The bucket size, in milliseconds. When you specify a value, the counts within each bucket are combined. For example, `3600000` creates one-hour buckets. When you omit this field, the service selects a resolution that fits the time range.
`countInstances`	boolean	No	Count individual occurrence instances (`true`) or distinct events (`false`). Default: `false`.

Response codes

Code	Description
200	The request was processed successfully. For operations on multiple objects, check the response body for per-item results.
400	The request couldn't be processed. The request body is missing, malformed, or contains invalid values.
401	Authentication failed. The API key is missing or invalid.
500	An unexpected error occurred. Try the request again. If the problem persists, contact Virtana support.

Request example

curl https://YOUR-API-ENDPOINT/v1/events:frequency \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s -S -d \
'{
  "query": {
    "timeRange": {
      "start": "1782416198966",
      "end":   "1782419798966"
    },
    "clause": {
      "filter": {
        "field": "source-type",
        "operation": "OP_EQUALS",
        "value": "cz"
      }
    }
  },
  "fields": [
    { "field": "severity" }
  ],
  "groupBy": [
    { "field": "severity" }
  ],
  "downsample": 900000
}'

Response example

{
  "timestamps": [
    "1782416198966",
    "1782417098966",
    "1782417998966",
    "1782418898966"
  ],
  "results": {
    "severity": {
      "values": [
        { "value": 5, "counts": ["276", "276", "276", "276"] },
        { "value": 4, "counts": ["757", "757", "757", "757"] },
        { "value": 3, "counts": ["62",  "64",  "64",  "81" ] }
      ]
    }
  }
}

Note

The event query service returns grouped field values in the results object as integers, not as enumeration names. Use the following mappings to interpret them:

severity: 0 is SEVERITY_DEFAULT, 1 is SEVERITY_DEBUG, 2 is SEVERITY_INFO, 3 is SEVERITY_WARNING, 4 is SEVERITY_ERROR, and 5 is SEVERITY_CRITICAL.
status: 0 is STATUS_DEFAULT, 1 is STATUS_OPEN, 2 is STATUS_SUPPRESSED, and 3 is STATUS_CLOSED.

In this section:

Event query API

Resource list

Get an event

Search events

Count events

Note

Get event frequency

Note

Search results