Metrics and Logs API

This page describes the available API endpoints for querying logs, traces, Kubernetes events, and metrics in groundcover, including how to authenticate and structure requests for general data retrieva

Authentication

Authentication is performed using an API key generated in the API Keys section of the groundcover console.

All API requests must include the API key in the Authorization header using the following format:

Authorization: Bearer <YOUR_API_KEY>

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

Rate Limits

groundcover APIs enforce rate limits on a per-client basis to ensure fair usage and system stability. Each client is allowed up to 150 requests per second and 1,000 requests per minute. A “client” is identified by the Authorization header, which typically represents an API key. This means that rate limits are applied independently for each API key used

Raw Prometheus API for Metrics

Use the following endpoint to query the groundcover Prometheus API:

https://app.groundcover.com/api/prometheus/api/v1/query

To see usage example on how to query metrics in groundcover see: Query metrics examples

For a complete Prometheus REST API documentation, and available operations, see: Prometheus HTTP API

Logs, Traces & Events API (gcQL)

Logs, traces, and Kubernetes events are queried with gcQL through the search endpoints:

https://api.groundcover.com/api/logs/v2/search
https://api.groundcover.com/api/traces/v2/search
https://api.groundcover.com/api/k8s/v2/events/search

For usage examples see: Query Data with gcQL

Legacy API (Clickhouse)

The following configurations are deprecated but may still be in use in older setups.

The legacy datasources is using a different API key than described above. The API key can be obtained by running: groundcover auth get-datasources-api-key

You can query the legacy API to execute SQL statements directly on the Clickhouse database.

Try the following structure:

curl https://ds.groundcover.com/ \
    -H "X-ClickHouse-Key: <DS-API-KEY-VALUE>" \
    --data "SELECT count() FROM logs LIMIT 1 FORMAT JSON"