> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/discover-fields-and-metrics.md).

# Discover Fields and Metrics

Find queryable fields, their values, and metric names before building API queries.

Use discovery endpoints to build queries from the fields and metrics available in your workspace.

### Authentication

Send `Authorization: Bearer <YOUR_API_KEY>` and `X-Backend-Id: <YOUR_BACKEND_ID>`. JSON requests also require `Content-Type: application/json`. The examples use `https://api.groundcover.com`; use your deployment's API URL for a self-hosted installation. Replace the example time range with one containing your data.

### Discover Fields for a Signal

**POST** `/api/search/keys`

Send `type` (a signal name or array of signal names), `limit` (1–10000), and optional `filter` (field-name search) or `sources` (structured scope).

```bash
curl --request POST 'https://api.groundcover.com/api/search/keys' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "logs",
  "limit": 100,
  "filter": "http"
}'
```

The response contains `keys` with `key`, `keyType`, `description`, and `type`, plus `isLimitReached`.

Supported signal names include `logs`, `traces`, `events`, `issues`, `entities`, `apm`, `ingestion_measurements`, `dbm_measurements_statement`, `monitors`, `dashboards`, `aws_cur`, `profiling_samples`, `rum_events`, and `rum_sessions`. Some signal types require the corresponding capability to be available in your backend. Use dedicated metric discovery below for metrics.

### Discover Values for a Field

**POST** `/api/search/values`

Send `type` (one signal), `key`, `limit`, and a time range for historical signals. Optional `filter` narrows returned values by text; optional `query` scopes discovery with a gcQL **filter only**, without pipes or aggregations. `query` takes precedence over `filterGroup` and `conditions`. Use simple AND conditions for reliable scoping: complex OR/NOT expressions that cannot be converted to conditions may be ignored. Discovery is intended for picker suggestions, so filters on the field being enumerated may be relaxed to suggest alternative values.

```bash
curl --request POST 'https://api.groundcover.com/api/search/values' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "start": "2026-10-28T10:00:00Z",
  "end": "2026-10-28T11:00:00Z",
  "type": "logs",
  "key": "workload",
  "limit": 50,
  "query": "namespace:production"
}'
```

A non-streaming response has `results: [{"value":"checkout-service"}]`, `isLimitReached`, and `done`. Set `enableStream: true` and use `curl -N` to receive `search_values` SSE snapshots instead. Check `done` and `error` on streamed responses. Values are capped at 100 per underlying search; narrow the scope or `filter` when `isLimitReached` is true.

### Discover Field/Value Suggestions Together

**POST** `/api/search/discovery`

Send `type`, `limit` (up to 100), and optional `filter`, `sources`, `conditions`, or `filterGroup`. This route supports `logs`, `traces`, `events`, `issues`, `entities`, `apm`, `monitors`, `dashboards`, `rum_events`, and `rum_sessions`. It returns `results` containing `key`/`value` suggestions and `isLimitReached`.

```bash
curl --request POST 'https://api.groundcover.com/api/search/discovery' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "logs",
  "limit": 20,
  "filter": "checkout"
}'
```

### Search Across Signals

| Endpoint                             | Request differences                                                                                 | Response                                                                              |
| ------------------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **POST** `/api/search/v2/keys`       | `types` array, `limit`, optional `filterKey`; include `start`, `end`, and `metricNames` for metrics | `keys` with `key`, `types`, `metricNames`, `description`; `done` and `isLimitReached` |
| **POST** `/api/search/v2/values`     | `types` array, `key`, `limit`, time range; optional `filterValue`, `query`, `metricNames`           | `search_values` SSE snapshots with `key`, `values`, `done`, `isLimitReached`          |
| **POST** `/api/search/v2/associated` | `key`, `limit`, `start`, `end`; optional `filterAssociated`, `filterValue`, `metricNames`           | Associated values as `search_values` SSE snapshots                                    |

The multi-signal routes support `logs`, `traces`, `events`, `metrics`, `rum`, `issues`, `entities`, `apm`, `ingestion`, `dbm_measurements_statement`, `aws_cur`, and `profiling_samples`. The spelling `ingestion` here differs from `ingestion_measurements` on the single-signal routes. For newer `rum_events`/`rum_sessions` domains, use the single-signal endpoints.

```bash
curl -N --request POST 'https://api.groundcover.com/api/search/v2/values' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "start": "2026-10-28T10:00:00Z",
  "end": "2026-10-28T11:00:00Z",
  "types": [
    "logs",
    "traces"
  ],
  "key": "workload",
  "limit": 50,
  "filterValue": "checkout"
}'
```

Each value item contains `value`, `types`, and `description`. These endpoints stream automatically; do not expect a single JSON response. Each event replaces the previous result snapshot. For `/values`, the same filter-only `query` restrictions described above apply.

For associated discovery, each `filterAssociated` entry has `type`, `key`, and `value`. For example:

```bash
curl -N --request POST 'https://api.groundcover.com/api/search/v2/associated' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "start": "2026-10-28T10:00:00Z",
  "end": "2026-10-28T11:00:00Z",
  "key": "workload",
  "limit": 50,
  "filterAssociated": [
    {
      "type": "logs",
      "key": "namespace",
      "value": "production"
    }
  ]
}'
```

### Discover Metric Names

**POST** `/api/metrics/names`

```bash
curl --request POST 'https://api.groundcover.com/api/metrics/names' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "start": "2026-10-28T10:00:00Z",
  "end": "2026-10-28T11:00:00Z",
  "limit": 50,
  "filter": "http"
}'
```

The required fields are `start`, `end`, and `limit` (up to 10000). Optional `sources` scopes the search; `required` is an array of metric names to include. The response has `metrics` (name, description, unit, type, highlights) and `isLimitReached`.

### Discover Metric Labels and Values

**POST** `/api/metrics/v2/keys` finds label names; **POST** `/api/metrics/v2/values` finds values for one label.

```bash
curl --request POST 'https://api.groundcover.com/api/metrics/v2/values' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "start": "2026-10-28T10:00:00Z",
  "end": "2026-10-28T11:00:00Z",
  "names": [
    "http_requests_total"
  ],
  "key": "status_code",
  "limit": 100
}'
```

Both routes require `start`, `end`, `names`, and `limit`. `names` must contain exactly one metric name, or `"*"` for all metrics. `/values` additionally requires `key`. Optional `filter` narrows the returned names/values; `sources` scopes the request. `/values` also accepts structured `conditions`.

`/keys` returns `keys: [{"name":"http_requests_total","keys":["status_code"]}]`. `/values` returns `values: [{"name":"http_requests_total","key":"status_code","values":["200","500"]}]`. Both include `isLimitReached`.

The keys limit must not exceed 1000. Values are capped at 1000; without `filter` or `conditions`, the values lookup limits the time window to the seven days ending at `end`. These are discovery limits, not metric-query retention limits.

The older `/api/metrics/keys` and `/api/metrics/values` routes remain available but use a single `name` field rather than the `names` array. Use the v2 routes above for new discovery clients, then [query the metric](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-metrics.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/discover-fields-and-metrics.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
