Query Logs

Search and aggregate log data over HTTP using gcQL queries - filter by any field, run full-text searches, and compute aggregations in a single request.

Endpoint

POST /api/logs/v2/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 Error Logs

Fetch the latest error logs with a selected set of fields:

curl 'https://api.groundcover.com/api/logs/v2/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": "level:error | sort by (_time desc) | fields _time, workload, namespace, content | limit 20"
  }'

Example Response:

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

Filtering by Multiple Fields

Different fields combine with AND; repeating the same field creates an OR. This query matches error logs from the prod or dev environments:

curl 'https://api.groundcover.com/api/logs/v2/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": "level:error env:prod env:dev | fields _time, env, workload, content | limit 20"
  }'

Exclusions use a - prefix (-level:debug), and explicit boolean logic is also supported: level:error AND (env:prod OR env:dev). See gcQL filters for the full syntax.

Full-Text Search

A bare keyword (no field prefix) runs an indexed full-text search over log content. This counts how many log lines from a workload contain "500":

curl 'https://api.groundcover.com/api/logs/v2/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": "workload:router 500 | stats count() as hits"
  }'

Example Response:

[
  { "hits": 2433 }
]

Prefer bare keywords (timeout, 500) over leading-wildcard patterns like content:*timeout* - keywords hit the full-text index, while a leading wildcard forces a full scan.

Aggregation: Errors per Workload

Count error logs grouped by workload, sorted by count:

curl 'https://api.groundcover.com/api/logs/v2/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": "level:error | stats by (workload) count() as errors | sort by (errors desc) | limit 10"
  }'

Example Response:

[
  { "workload": "sensor", "errors": 652050 },
  { "workload": "custom-metrics", "errors": 292511 },
  { "workload": "ingress-gateway", "errors": 133992 }
]

Pagination

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

# Page 1
"query": "level:error | sort by (_time desc) | fields _time, workload, content | limit 200"

# Page 2
"query": "level:error | sort by (_time desc) | fields _time, workload, content | offset 200 | limit 200"

Best Practices

1. Narrow the time range: keep start/end as tight as your use case allows, and widen only if needed.

2. Lead with a selective filter: a specific workload, namespace, or level bounds the scan; on high-volume environments add a keyword predicate too.

3. Aggregate on the server: one | stats query with count() if (condition) beats fetching raw rows and counting client-side.

4. Always bound results with | limit N.