Events API Reference

All event query APIs are available through the GraphQL endpoint at /events-query. Operations use POST with a JSON body containing a query key.

Replace <your-instance> with your Kloudfuse hostname and <sa-token> with a valid Service Account token.

curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/events-query" \
     -d '{"query": "..."}'
bash

For Service Account token setup, see Authentication. See graphql for general guidance on using the GraphQL client. Failed operations report errors in the standardized format described in API Response Codes.

For what an event’s fields mean, see The event model.

Filtering events

Most operations take an EventFilter, a boolean expression over eq, neq, startsWith, endsWith, contains, regex, nregex, and keyExists, combined with and, or, and not. Each comparison operator (except keyExists) takes a Selector — { name, value }.

name is either a top-level event field, prefixed with @ (for example, @severity, @source), or a bare label name (for example, kube_namespace) — see The event model for the field list and labelNames for the labels available in your environment.

Filter to error-severity Kubernetes events
{
  "and": [
    { "eq": { "name": "@severity", "value": "error" } },
    { "eq": { "name": "@source", "value": "kubernetes" } }
  ]
}
json

events

Gets a list of events based on time, filters, and a specified limit.

Parameters:

Parameter Type Required Description

timestamp

Time

No

Events start at this timestamp; defaults to now().

durationSecs

int

No

Duration to look back, in seconds; defaults to 300.

filter

EventFilter

No

See Filtering events.

offset

int

No

Skip this many results — use for paging through large result sets.

limit

int

No

Maximum rows to return; defaults to 200.

sortBy

EventSortBy

No

TIMESTAMP, SOURCE, EVENT_ID, AGGREGATION_KEY, SEVERITY, EVENT_TYPE, or TITLE; defaults to TIMESTAMP.

sortOrder

SortOrder

No

Asc or Desc; defaults to Desc.

Returns a list of Event objects — see The event model for field meanings. labels is only populated if requested in the response selection.

List the 5 most recent error-severity events from Kubernetes
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/events-query" \
     -d '{
       "query": "{ events(durationSecs: 3600, limit: 5, filter: { and: [{ eq: { name: \"@severity\", value: \"error\" } }, { eq: { name: \"@source\", value: \"kubernetes\" } }] }) { id title severity source eventType timestamp } }"
     }'
bash
Response (truncated)
{
  "data": {
    "events": [
      {
        "id": "e702f735-a97f-4b48-8144-244c805076b4",
        "title": "Events from the Pod default/checkout-7d6258b6-x0k2",
        "severity": "error",
        "source": "kubernetes",
        "eventType": "kubernetes_apiserver",
        "timestamp": "2026-09-15T20:09:05Z"
      }
    ]
  }
}
json

eventCounts

Gets the count of events, optionally grouped by rounded timestamp, and/or by a facet or label.

Parameters:

Parameter Type Required Description

timestamp

Time

No

Events start at this timestamp; defaults to now().

durationSecs

int

No

Duration to look back, in seconds; defaults to 300.

filter

EventFilter

No

See Filtering events.

countUnique

string

No

A facet (@-prefixed) or label name to compute a distinct-value (cardinality) count for, instead of a plain event count.

groupBys

[string]

No

Facets and/or labels to group by; defaults to no grouping.

roundSecs

int

No

Bucket size, in seconds, to round the timestamp to. Omit to count over the full time range as a single bucket.

topOrBottomK

TopOrBottomK

No

{ type: Top | Bottom, k: Int } — keep only the top or bottom k groups by count, per timestamp bucket.

limit

int

No

Maximum rows to return; defaults to the instance’s configured Pinot default limit.

Returns a list of EventCount objects, each with timestamp, count, keys (the groupBys field names), and values (the corresponding group’s values).

Count Kubernetes events per 5-minute bucket, grouped by severity
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/events-query" \
     -d '{
       "query": "{ eventCounts(durationSecs: 3600, roundSecs: 300, groupBys: [\"@severity\"], filter: { eq: { name: \"@source\", value: \"kubernetes\" } }) { timestamp count keys values } }"
     }'
bash
Response (truncated)
{
  "data": {
    "eventCounts": [
      { "timestamp": "2026-09-15T20:05:00Z", "count": 812, "keys": ["@severity"], "values": ["info"] },
      { "timestamp": "2026-09-15T20:05:00Z", "count": 3,   "keys": ["@severity"], "values": ["error"] }
    ]
  }
}
json

facetValues

Gets the distinct values of a facet (a top-level event field, @-prefixed) with their counts, over the given time range.

Parameters:

Parameter Type Required Description

facetName

string

Yes

The facet to enumerate — for example, @source.

timestamp

Time

No

Events start at this timestamp; defaults to now().

durationSecs

int

No

Duration to look back, in seconds; defaults to 300.

filter

EventFilter

No

See Filtering events.

limit

int

No

Maximum values to return; defaults to the instance’s configured Pinot default limit.

Returns a list of ValueCount objects (value, count).

Distinct sources seen in the last hour
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/events-query" \
     -d '{"query": "{ facetValues(durationSecs: 3600, facetName: \"@source\") { value count } }"}'
bash
Response
{
  "data": {
    "facetValues": [
      { "value": "kubernetes", "count": 174656 },
      { "value": "kafka", "count": 240 },
      { "value": "helm", "count": 120 },
      { "value": "System", "count": 3 }
    ]
  }
}
json

facetNames

Gets the list of available facet names. Takes no arguments and is not scoped to a time range.

List facet names
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/events-query" \
     -d '{"query": "{ facetNames }"}'
bash

labelValues

Gets the distinct values of a label with their counts, over the given time range.

Parameters:

Parameter Type Required Description

labelName

string

Yes

The label to enumerate — for example, kube_namespace.

timestamp

Time

No

Events start at this timestamp; defaults to now().

durationSecs

int

No

Duration to look back, in seconds; defaults to 300.

filter

EventFilter

No

See Filtering events.

limit

int

No

Maximum values to return; defaults to the instance’s configured Pinot default limit.

Returns a list of ValueCount objects (value, count).

labelNames

Gets the list of available label names for events in the specified time range.

Parameters:

Parameter Type Required Description

timestamp

Time

No

Events start at this timestamp; defaults to now().

durationSecs

int

No

Duration to look back, in seconds; defaults to 300.

filter

EventFilter

No

See Filtering events.
List label names seen on Kubernetes events in the last hour
curl -H "Authorization: Bearer <sa-token>" \
     -H "Content-Type: application/json" \
     -X POST "https://<your-instance>/events-query" \
     -d '{"query": "{ labelNames(durationSecs: 3600, filter: { eq: { name: \"@source\", value: \"kubernetes\" } }) }"}'
bash
Response (truncated)
{
  "data": {
    "labelNames": ["kube_cluster_name", "kube_namespace", "kube_name", "kube_kind", "orchestrator", "..."]
  }
}
json

Error handling

GraphQL errors are returned with HTTP 200 in an errors array alongside a null data value — see Logs API error handling for the response shape and common causes.

See Also