Event query service

The event query service provides resources for retrieving and searching events. To modify events, use the event management service.

Resource list

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

GET /v1/events/{id}

Retrieve a single event by its identifier.

Path parameters

id (string, required)

The identifier of the event to retrieve.

Query parameters

occurrenceIds (string, optional, repeatable)

One or more occurrence identifiers. When omitted, returns the most recent occurrence. Repeat the parameter to request multiple occurrences: ?occurrenceIds=occ1&occurrenceIds=occ2.

fields (string, optional, repeatable)

Field names to include in the response. When omitted, all fields are returned.

Status codes

• 200 (success)
• 400 (invalid request parameters)
• 401 (missing or invalid API key)

Example

RequestResponse

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

{
  "result": {
    "id": "AAAABWRDWOPER3lzOFI2tSCG49g=",
    "entity": "/entities/host-prod-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"
      }
    ]
  }
}

---

POST /v1/events:search

Search for events using filter, time range, severity, and pagination criteria.

Request template

{
  "query": {
    "timeRange": {
      "start": <unix-ms>,
      "end": <unix-ms>
    },
    "clause": {
      "filter": {
        "field": "<field-name>",
        "operation": "<operation>",
        "value": "<value>"
      }
    },
    "severities": ["<severity>"],
    "statuses": ["<status>"],
    "sortBy": [
      { "byField": { "field": "<field-name>", "order": "SORT_ORDER_DESC" } }
    ],
    "pageInput": {
      "limit": <integer>,
      "cursor": "<cursor>",
      "direction": "DIRECTION_FORWARD"
    },
    "fields": [
      { "field": "<field-name>" }
    ]
  }
}

Request fields

query (object, required)

Search criteria.

timeRange (object, optional)

The time range to search. Times are Unix timestamps in milliseconds.

start (integer, optional)

Start of the time range, as a Unix timestamp in milliseconds.

end (integer, optional)

End of the time range, as a Unix timestamp in milliseconds.

clause (object, optional)

A filter clause applied to event fields. Clauses can be nested using and, or, and not combinators.

• Simple filter: { "filter": { "field": "summary", "operation": "OP_CONTAINS", "value": "timeout" } }
• Combined filter: { "and": { "clauses": [ { "filter": {...} }, { "filter": {...} } ] } }

Supported operations: 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, OP_EXISTS.

severities (array of strings, optional)

Filter by severity. Multiple values are combined with OR.

• SEVERITY_DEFAULT
• SEVERITY_DEBUG
• SEVERITY_INFO
• SEVERITY_WARNING
• SEVERITY_ERROR
• SEVERITY_CRITICAL

statuses (array of strings, optional)

Filter by status. Multiple values are combined with OR.

• STATUS_DEFAULT
• STATUS_OPEN
• STATUS_SUPPRESSED
• STATUS_CLOSED

sortBy (array of objects, optional)

Sort criteria, applied in decreasing priority. Use byField to sort by a field name and set order to SORT_ORDER_ASC or SORT_ORDER_DESC.

pageInput (object, optional)

Pagination controls.

limit (integer, optional)

Maximum number of results to return per page. Defaults to a system limit when not specified.

cursor (string, optional)

Pagination cursor from a prior response's pageInfo.endCursor (forward) or pageInfo.startCursor (backward).

direction (string, optional)

Pagination direction: DIRECTION_FORWARD (default) or DIRECTION_BACKWARD.

activeCriteria (string, optional)

Determines which occurrences are considered active within the time range.

• BY_TIMERANGE (default) — occurrences last updated within the time range
• BY_OCCURRENCES — occurrences whose interval intersects the time range

fields (array of objects, optional)

Fields to include in each result. When omitted, all fields are returned. Example: [{ "field": "eventClass" }].

field (string, optional)

The name of a field to include, for example eventClass.

Status codes

• 200 (success)
• 400 (invalid request parameters)
• 401 (missing or invalid API key)

Example

RequestResponse

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 }
  }
}'

{
  "results": [
    {
      "id": "AAAABWRDWOPER3lzOFI2tSCG49g=",
      "entityName": "host-prod-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..."
  }
}

---

POST /v1/events:count

Count events matching a query, optionally grouped by one or more field values.

Request template

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

Request fields

query (object, optional)

Search criteria. When omitted, counts all events. Uses the same structure as the query field of the search resource.

fields (array of objects, optional)

Fields to group results by. Each entry requires a field string. When omitted, returns a single total count.

countInstances (boolean, optional, default = false)

When true, counts individual occurrence instances rather than distinct events.

Status codes

• 200 (success)
• 400 (invalid request parameters)
• 401 (missing or invalid API key)

Example

RequestResponse

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

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

Note

Field values in results are returned as raw enum integers. For severity: 0=DEFAULT, 1=DEBUG, 2=INFO, 3=WARNING, 4=ERROR, 5=CRITICAL. For status: 0=DEFAULT, 1=OPEN, 2=SUPPRESSED, 3=CLOSED.

---

POST /v1/events:frequency

Return a time series of event counts over a query's time range. Results can be grouped by field values and downsampled to a coarser time resolution.

Request template

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

Request fields

query (object, required)

Search criteria, including the required time range. Uses the same structure as the query field of the search resource.

Info

A timeRange is required for frequency requests.

fields (array of objects, required)

Fields to include in results. Each entry requires a field string.

groupBy (array of objects, required)

Fields to group the time series by. Each entry requires a field string.

downsample (integer, optional)

Bucket size in milliseconds. When set, counts within each bucket are combined. When omitted, the backend selects a resolution appropriate for the time range. Example: 3600000 for one-hour buckets.

countInstances (boolean, optional, default = false)

When true, counts individual occurrence instances rather than distinct events.

Status codes

• 200 (success)
• 400 (invalid request parameters)
• 401 (missing or invalid API key)

Example

RequestResponse

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
}'

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