Query Kubernetes Events

Search and aggregate Kubernetes events over HTTP using gcQL queries - surface warnings, group events by reason, and track cluster activity.

Endpoint

POST /api/k8s/v2/events/search

Authentication

This endpoint requires API Key authentication via the Authorization header.

Headers

Header	Required	Description
Authorization	Yes	Bearer token with your API key
Content-Type	Yes	Must be application/json
X-Backend-Id	Only for multi-backend accounts	Your backend identifier, found under Settings → Access → API Keys (details)

Request Body

Parameter	Type	Required	Description
start	string	Yes	Start of the time range (RFC3339 / ISO 8601)
end	string	Yes	End of the time range (RFC3339 / ISO 8601)
query	string	Yes	The gcQL query to execute

Examples

Recent Warning Events

Fetch the latest Warning-type events:

curl 'https://api.groundcover.com/api/k8s/v2/events/search' \
  -H 'authorization: Bearer <YOUR_API_KEY>' \
  -H 'content-type: application/json' \
  --data-raw '{
    "start": "2026-08-22T14:00:00Z",
    "end": "2026-08-22T15:00:00Z",
    "query": "type:Warning | sort by (_time desc) | fields _time, reason, entity_workload, message | limit 20"
  }'

Example Response:

[
  {
    "_time": "2026-08-22T14:04:09.000000000Z",
    "reason": "BackOff",
    "entity_workload": "payment-service",
    "message": "Back-off restarting failed container"
  },
  {
    "_time": "2026-08-22T14:03:51.312814000Z",
    "reason": "FailedScheduling",
    "entity_workload": "checkout-service",
    "message": "0/7 nodes are available: 4 Insufficient cpu."
  }
]

Events by Reason

Count events grouped by reason to see what dominates cluster activity:

curl 'https://api.groundcover.com/api/k8s/v2/events/search' \
  -H 'authorization: Bearer <YOUR_API_KEY>' \
  -H 'content-type: application/json' \
  --data-raw '{
    "start": "2026-08-22T14:00:00Z",
    "end": "2026-08-22T15:00:00Z",
    "query": "* | stats by (reason) count() as events | sort by (events desc) | limit 10"
  }'

Example Response:

[
  { "reason": "BackOff", "events": 43229 },
  { "reason": "FailedScheduling", "events": 12417 },
  { "reason": "Unhealthy", "events": 8203 }
]

Filtering by Specific Reasons

Match several reasons at once with in():

curl 'https://api.groundcover.com/api/k8s/v2/events/search' \
  -H 'authorization: Bearer <YOUR_API_KEY>' \
  -H 'content-type: application/json' \
  --data-raw '{
    "start": "2026-08-22T14:00:00Z",
    "end": "2026-08-22T15:00:00Z",
    "query": "reason:in(OOMKilling, BackOff, FailedScheduling) | fields _time, reason, entity_workload, message | limit 20"
  }'

Best Practices

1. Start from type:Warning when hunting for problems - normal events usually dominate the volume.

2. Group by reason to get a quick picture before drilling into raw events.

3. Discover field names with a * | field_names query if you are unsure what is available to filter on.

4. Always bound results with | limit N.