> 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/monitor-issues-api.md).

# Monitor Issues API

Search monitor evaluation history, filter firing evaluations, and inspect instance timelines.

The issues API searches monitor evaluation history across all states, including evaluations that are not firing. Without a status filter, results include all evaluation states in the selected time range. A historical Alerting evaluation does not mean the monitor is still firing now.

### Authentication

Use an [API key](https://docs.groundcover.com/administer/api-keys.md) with at least Viewer (`read`) permissions. Include `Authorization: Bearer <YOUR_API_KEY>` and `X-Backend-Id: <YOUR_BACKEND_ID>`. JSON requests require `Content-Type: application/json`.

The examples use `https://api.groundcover.com`. Self-hosted installations use their own API URL and an API key issued in that environment.

### Search Issues

**POST** `/api/monitors/issues/search`

Use a `query` gcQL string or a structured `pipeline` (one is required). `start` and `end` bound the search. Optional `filters` adds a gcQL filter; `sources` accepts structured source conditions.

To retrieve firing evaluations, use **`status:Alerting`** with a capital `A`. `state:Alerting` is a supported alias; `status` is the field exposed by discovery. State values are case-sensitive. The following example returns firing evaluations:

```bash
curl --request POST 'https://api.groundcover.com/api/monitors/issues/search' \
  --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",
  "query": "status:Alerting | fields _time, monitor_name, status | sort by (_time desc) | limit 20"
}'
```

The HTTP `200` response is an object containing `data` (rows) and `valueFieldHints` (numeric fields); it is not the bare array returned by the older log search API. A query must select rows or aggregate them. To include every evaluation state, use `* | limit 20` or `* | stats count() as total_evaluations`. `count()` counts evaluations, not distinct incidents; longer time ranges may use rollups.

### Aggregate Issues over Time

**POST** `/api/monitors/issues/search-time-series`

Adds required `bucketDuration`, optional `valueField`, and optional numeric `fillValue` to the search body. The query must contain an aggregation. `valueField` can name one numeric result column or a comma-separated list; multiple columns generate a `metric_name` label. Do not also return a column named `metric_name` when using multiple value fields. Omitted `fillValue` leaves empty buckets as null.

```bash
curl --request POST 'https://api.groundcover.com/api/monitors/issues/search-time-series' \
  --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",
  "query": "status:Alerting | stats count() as firing_evaluations",
  "bucketDuration": "5m",
  "valueField": "firing_evaluations",
  "fillValue": 0
}'
```

The response contains `data`, an array of labeled time series. This example counts firing evaluations in each bucket. Remove `status:Alerting` to count evaluations across all states.

### Query Instances

Issue searches, instance queries, summaries, and timelines use shared runtime endpoints under `/api/monitors`. They are separate from the [v2 definition-management API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/monitors-v2-api.md).

**POST** `/api/monitors/instances/query`

```bash
curl --request POST 'https://api.groundcover.com/api/monitors/instances/query' \
  --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": 20,
  "skip": 0,
  "sortBy": "lastFiringStart",
  "order": "desc",
  "bucketResolution": "smallLine"
}'
```

The response contains `results` and `hasMonitors`. Each result includes monitor metadata, instance state, labels, silences, and evaluation values. Increment `skip` by the page size until a page contains fewer than `limit` results.

`bucketResolution` is required and accepts `lowest`, `smallBar`, `bigBar`, `smallLine`, or `bigLine`. Sort by `lastStateStart`, `active`, `alertingPercent`, `lastFiringStart`, `lastResolved`, or `firstFiringStart`; `order` is `asc` or `desc`. Use structured `conditions` to filter monitors and `sources` to scope source data.

### Timelines and Filter Discovery

All the following routes use POST and accept JSON with a time range:

| Endpoint                           | Additional inputs                                                                                       | Result                                           |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `/api/monitors/timeline`           | Optional `conditions`, `sources`, `bucketResolution`                                                    | `results` with monitor-state series              |
| `/api/monitors/instances/timeline` | `conditions` selecting exactly one monitor; optional `sources`, `bucketResolution`                      | Array of resource/result series for that monitor |
| `/api/monitors/instances/velocity` | Required `bucketResolution`; optional `groupBy` (`severity` or `monitor_name`), `conditions`, `sources` | Issue-count series                               |
| `/api/monitors/summary/filters`    | Optional `sources`, `required` column descriptors                                                       | Available summary filter facets                  |
| `/api/monitors/instances/filters`  | Optional `sources`, `required`, `bucketResolution`                                                      | Available instance filter facets                 |
| `/api/monitors/labels/keys`        | Required `limit`; optional `filter`, `sources`                                                          | `keys`, `isLimitReached`                         |
| `/api/monitors/labels/values`      | Required `key`, `limit`; optional `filter`, `conditions`, `sources`                                     | `key`, `values`, `isLimitReached`                |
| `/api/monitors/labels/discovery`   | Required `limitByKey`; optional `filter`, `conditions`, `sources`                                       | Label discovery results                          |

For example, discover label values to use in a silence or notification route:

```bash
curl --request POST 'https://api.groundcover.com/api/monitors/labels/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",
  "key": "namespace",
  "limit": 100
}'
```

See [Query Monitors Summary](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-monitors-summary.md) for structured condition examples and [Silences API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/silences-api.md) for suppressing notifications.


---

# 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/monitor-issues-api.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.
