> 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/monitors-v2-api.md).

# Monitors v2 API

Manage typed monitor definitions, search, revisions, and Terraform exports.

The v2 API uses a typed JSON `spec` for monitor definitions. It is available only on backends where the monitors-v2 capability is enabled; otherwise these routes return `404`. For backends without this capability, use [Legacy Monitor Read Compatibility](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/legacy-monitor-reads.md) to list monitors and retrieve their YAML definitions.

The URL prefix is `/api/v2/monitors`, which is different from the unified silence prefix `/api/monitors/v2/silences`.

### Authentication

Use an [API key](https://docs.groundcover.com/administer/api-keys.md) with at least Viewer (`read`) permissions for reads and Editor (`write`) permissions for writes. 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.

### Create a Monitor

**POST** `/api/v2/monitors`

The body contains `spec` and optional `isProvisioned`. The following creates a paused monitor using notification routes:

```bash
curl --request POST 'https://api.groundcover.com/api/v2/monitors' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "spec": {
    "name": "Checkout error logs",
    "type": "logs",
    "severity": "S2",
    "isPaused": true,
    "evaluationNoDataState": "OK",
    "evaluationErrorState": "Error",
    "evaluationInterval": {
      "interval": "1m",
      "pendingFor": "1m"
    },
    "issueDisplay": {
      "title": "Checkout error logs above threshold"
    },
    "notificationSettings": {
      "notificationRoutes": {}
    },
    "model": {
      "query": {
        "expression": "workload:checkout level:error | stats count() errors_total",
        "rollup": "5m"
      },
      "thresholds": [
        {
          "firing": {
            "operator": "gt",
            "values": [
              10
            ]
          }
        }
      ]
    }
  }
}'
```

Returns HTTP `201` with `{"uuid":"00000000-0000-4000-8000-000000000001"}`. The server assigns the UUID.

### Definition Fields

| Field in `spec`                                  | Description                                                                                      |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `name`, `type`                                   | Required name and data type. Type determines the query language                                  |
| `severity`, `team`, `category`, `tags`, `labels` | Optional metadata; label keys beginning `_gc_` are reserved                                      |
| `isPaused`                                       | Whether evaluation is paused                                                                     |
| `evaluationNoDataState`                          | Required: `OK`, `NoData`, or `Alerting`                                                          |
| `evaluationErrorState`                           | Required: `OK`, `Error`, or `Alerting`                                                           |
| `evaluationInterval`                             | Required `interval` and optional `pendingFor` duration                                           |
| `issueDisplay`                                   | Required non-empty `title`; optional description and context labels                              |
| `notificationSettings`                           | Exactly one of `notificationRoutes: {}`, `noNotifications: {}`, or `destinations: {apps: [...]}` |
| `model.query`                                    | `expression`, `rollup` where the data type uses time, and `rollupFunction` for metrics           |
| `model.thresholds`                               | At most one threshold entry, with a `firing` operator and values; optional `recovery` condition  |

Use the typed JSON `spec` shown above for all definition writes. Query language follows `type`: metrics use MetricsQL; logs, traces, events, and other gcQL data types use gcQL.

### Read, Update, and Delete

There is no single-monitor GET route in this API. Read one or more IDs with **POST** `/api/v2/monitors/batch/read`:

```bash
curl --request POST 'https://api.groundcover.com/api/v2/monitors/batch/read' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "monitorUUIDs": [
    "00000000-0000-4000-8000-000000000001"
  ]
}'
```

HTTP `200` returns `fetchedCount`, `failedCount`, a `monitors` map keyed by UUID, and per-ID `errors`. Each map value includes `uuid`, `backendId`, origin/provisioning metadata, timestamps, and `spec`. Unknown, deleted, and out-of-scope IDs appear in `errors`.

**PUT** `/api/v2/monitors/{uuid}` replaces the complete definition using `{"spec": {...}}`, in the same shape as the creation example. It returns `204`. To pause or resume, read the current entity, change `spec.isPaused` to `true` or `false`, and submit the full `spec`. Preserve the other fields.

{% hint style="warning" %}
PUT does not support revision or ETag/`If-Match` preconditions. A concurrent edit made after your read can be silently overwritten, including when you only intend to pause or resume. Coordinate with other users and automation so only one writer changes this monitor, then read its latest definition immediately before editing and submitting the full `spec`. Rereading alone does not prevent the race. There is no separate pause-only update endpoint in v2.
{% endhint %}

There is no v2 batch-write endpoint. For multiple creates, updates, deletes, or pause/resume changes, send one v2 request per monitor and check each response. Batch read is available for fetching the current definitions together.

**DELETE** `/api/v2/monitors/{uuid}` returns `204`:

```bash
curl --request DELETE 'https://api.groundcover.com/api/v2/monitors/00000000-0000-4000-8000-000000000001' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>'
```

### Search Definitions

**POST** `/api/v2/monitors/search` accepts a required `query` gcQL string. `start` and `end` bound issue data if the query joins issues; monitor definitions themselves have no time axis.

```bash
curl --request POST 'https://api.groundcover.com/api/v2/monitors/search' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "* | limit 20"
}'
```

Returns HTTP `200` with `data` (row objects) and `valueFieldHints` (numeric field candidates). Use gcQL projection, sorting, `limit`, and `offset` to shape and paginate results. See [Query Data with gcQL](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-data-gcql.md).

### Revisions and Restore

**GET** `/api/v2/monitors/{uuid}/revisions?limit=20&skip=0`

`limit` is required; `skip` defaults to zero. The response contains `revisions` in newest-first order and `hasNextPage`. An unknown UUID or a monitor with no recorded revisions returns an empty list. Restore a previous definition by taking its recorded `spec` and submitting it through the normal PUT update.

```bash
curl --request GET 'https://api.groundcover.com/api/v2/monitors/00000000-0000-4000-8000-000000000001/revisions?limit=20&skip=0' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>'
```

### Export Terraform

**POST** `/api/v2/monitors/export`

```bash
curl --request POST 'https://api.groundcover.com/api/v2/monitors/export' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "uuids": [
    "00000000-0000-4000-8000-000000000001"
  ],
  "format": "terraform"
}' \
  --output monitors.tf
```

`uuids` must contain 1–1,000 non-zero UUIDs; the only supported `format` is `terraform`. HTTP `200` returns plain-text HCL with `groundcover_monitor_v2` resources. Duplicate UUIDs are rendered once. Missing, deleted, out-of-scope, or non-exportable monitors produce comments in the HCL rather than failing the request; inspect the file before applying it.

### Test Notification Routing

**POST** `/api/monitors/test`

Notification testing uses this shared endpoint; there is no separate `/api/v2/monitors/test` route. Its request fields differ from the v2 definition `spec`.

Requires at least Editor (`write`) permissions, including dry runs with `send_notifications: false`.

| Field                  | Required | Description                                                                          |
| ---------------------- | -------- | ------------------------------------------------------------------------------------ |
| `monitor_name`         | Yes      | Display name for the test                                                            |
| `trigger`              | Yes      | `Alerting` or `Normal`                                                               |
| `labels`               | No       | Label map used to match routes                                                       |
| `send_notifications`   | No       | Defaults to false. Set true to actually send notifications                           |
| `severity`             | No       | Severity attached to the test                                                        |
| `display`              | No       | `header` and `description` templates                                                 |
| `notificationSettings` | No       | Direct `connectedApps` IDs and per-app `connectedAppParams`; bypasses route matching |
| `query`                | No       | Query metadata such as `expression`, `data_type`, `instant_rollup`                   |
| `threshold`            | No       | Threshold text for notification templates                                            |

This checks delivery configuration; it does not evaluate the monitor's query. The following request previews route matching without sending notifications:

```bash
curl --request POST 'https://api.groundcover.com/api/monitors/test' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
  "monitor_name": "Checkout error logs",
  "trigger": "Alerting",
  "labels": {
    "team": "platform"
  },
  "severity": "S2",
  "send_notifications": false
}'
```

The HTTP `200` response contains `matched_routes`, with route and destination IDs, names, destination type, `success`, and an optional `message` for each result. Set `send_notifications` to true only when ready to deliver a test.

### Runtime Queries

Use [Monitor Issues API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/monitor-issues-api.md) for evaluation history, instances, and timelines, and [Query Monitors Summary](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-monitors-summary.md) for evaluation summaries. These shared runtime endpoints retain their `/api/monitors` paths; definition management uses `/api/v2/monitors`.


---

# 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/monitors-v2-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.
