Query Data with gcQL

Query logs, traces, and Kubernetes events over HTTP using gcQL, groundcover's pipe-based query language. All signals share the same request structure and response format.

groundcover exposes a search endpoint per data type, all sharing the same request structure and all powered by gcQL - the same query language used in the platform's Data Explorer, dashboards, and monitors. Anything you can express in the product's search bar can be executed through these endpoints: filtering, field projection, aggregations, sorting, joins, and more.

Endpoints

Data type	Endpoint
Logs	POST /api/logs/v2/search
Traces	POST /api/traces/v2/search
Kubernetes Events	POST /api/k8s/v2/events/search

The base URL for all endpoints is https://api.groundcover.com.

Self-hosted (onPrem / airGapped) deployments use their own API URL. Replace https://api.groundcover.com with your environment's endpoint everywhere in this section, and use an API key generated in that environment's console - API keys are only valid for the environment that issued them.

Authentication

All endpoints require an API key passed in the Authorization header:

Authorization: Bearer <YOUR_API_KEY>

If your account is associated with multiple backends, also include the X-Backend-Id header:

X-Backend-Id: <YOUR_BACKEND_ID>

To locate your Backend ID, navigate to Settings → Access, open the API Keys tab, and find it in the section header.

Request Body

All search endpoints accept the same JSON body:

Parameter	Type	Required	Description
start	string	Yes	Start of the time range, RFC3339 / ISO 8601 (e.g. "2026-08-22T14:00:00Z")
end	string	Yes	End of the time range, RFC3339 / ISO 8601
query	string	Yes	The gcQL query to execute

Example Request Body:

{
  "start": "2026-08-22T14:00:00Z",
  "end": "2026-08-22T15:00:00Z",
  "query": "level:error | fields _time, workload, content | limit 20"
}

Writing gcQL Queries

A gcQL query starts with a filter expression (or * to match everything) followed by pipe operations:

<filter> | pipe1 | pipe2 | ...

For example, counting error logs per workload:

level:error | stats by (workload) count() as errors | sort by (errors desc) | limit 10

A few rules of thumb for queries over the API:

• Always end with | limit N to bound the result size.

• Filters alone return no data - pipe to | fields, | stats, or | limit to select what comes back.

• Prefer selective filters (a specific workload, namespace, or level) over *, and keep time ranges as narrow as your use case allows. Both dramatically reduce query cost.

• Use | fields to select only the columns you need and keep responses small.

• The request's start and end set the time window - use the _time field inside the query only for sub-windows or offsets.

See the full gcQL reference for all filters, pipes, and aggregation functions.

Response

The response is a JSON array of row objects. The shape of each row depends on the query: raw record queries return the record fields (or the ones selected with | fields), and aggregation queries return the group-by fields plus the computed values.

[
  {
    "_time": "2026-08-22T15:50:56.503949956Z",
    "workload": "checkout-service",
    "content": "failed to process payment: connection timeout"
  }
]

Pagination

Paginate with the offset and limit pipes, keeping the same time range and a stable sort order across pages:

level:error | sort by (_time desc) | fields _time, workload, content | limit 200
level:error | sort by (_time desc) | fields _time, workload, content | offset 200 | limit 200
level:error | sort by (_time desc) | fields _time, workload, content | offset 400 | limit 200

For aggregation queries, prefer refining the query (tighter filters, higher-level grouping) over paginating through a large result set.

Per-Signal Examples

• Query Logs

• Query Traces

• Query Kubernetes Events

APM measurements (pre-aggregated request, error, and latency data) are also queried with gcQL, through their own endpoints - see Query APM Measurements.