# Watchdog and monitoring endpoints

> Read Watchdog targets and security scans, current uptime status, uptime and latency history, and per-target metrics, over the Vigilbase One API.

Source: https://docs.vigilbase.com/one/api/watchdog-and-monitoring

[Watchdog](https://docs.vigilbase.com/one/services/watchdog) checks your public domains for uptime, latency and SSL, and scans them for security issues. These endpoints read its results, add targets and start scans. Sign-in, permissions, rate limits and error shapes are on [Vigilbase One API](https://docs.vigilbase.com/one/api).

These are v1 operations, on `https://api.vigilbase.com/one/v1`:

| Method and path | Permission | CLI command |
| --- | --- | --- |
| `GET /watchdog-scans` | `read:monitoring` or `read:partner_monitoring` | `vigilbase watchdog scans` |
| `GET /customers/{customerId}/watchdog-targets` | `read:monitoring` or `read:partner_monitoring` | `vigilbase customers watchdog-targets <id>` |
| `POST /customers/{customerId}/watchdog-targets` | `write:monitoring` or `write:partner_services` | |
| `GET /customers/{customerId}/watchdog-scans` | `read:monitoring` or `read:partner_monitoring` | `vigilbase customers watchdog-scans <id>` |
| `POST /customers/{customerId}/watchdog-scans` | `write:monitoring` or `write:partner_services` | |
| `GET /customers/{customerId}/monitoring/targets` | `read:monitoring` | `vigilbase monitoring targets <id>` |
| `GET /customers/{customerId}/monitoring/status` | `read:monitoring` | `vigilbase monitoring status <id>` |
| `GET /customers/{customerId}/monitoring/history` | `read:monitoring` | `vigilbase monitoring history <id>` |
| `GET /monitoring/metrics` | `read:monitoring` | `vigilbase monitoring metrics <target-id>…` |
| `GET /customers/{customerId}/incidents` | `read:customers` | |
| `POST /customers/{customerId}/incidents/{incidentId}/acknowledge` | `read:customers` | |

These have no v1 operation yet, and are on `https://one.vigilbase.com`:

| Method and path | Permission | CLI command |
| --- | --- | --- |
| `GET /api/account/watchdog/targets` | `read:monitoring` or `read:partner_monitoring` | `vigilbase watchdog list` |
| `GET /api/monitoring/probes/health` | `read:monitoring` | `vigilbase monitoring probe-health` |

`GET /watchdog-scans` and `GET /api/account/watchdog/targets` read your own organisation and take no customer ID. The `/customers/{customerId}/…` operations take a customer ID in the path: your own, or for a partner organisation, a customer it manages. Targets Vigilbase marks as internal never appear.

Lists are [cursor pages](https://docs.vigilbase.com/one/api#pagination), and times are ISO 8601 strings.

The CLI's `monitoring health` and `monitoring probes` commands read Vigilbase's own monitoring infrastructure and are for Vigilbase staff; customer sign-ins get `403`.

## Your Watchdog targets and scans

`GET /api/account/watchdog/targets` lists your targets, newest first. It isn't paged:

```json
{
  "success": true,
  "customer": { "id": "…", "name": "…", "domain": "…", "status": "customer", "isPartner": false },
  "targets": [
    {
      "id": "…",
      "domain": "example.com",
      "displayName": "Example",
      "uptimeStatus": "up",
      "uptime24h": 100,
      "uptime7d": 99.98,
      "avgLatencyMs": 182,
      "lastCheckAt": "2026-10-31T08:15:00.000Z"
    }
  ]
}
```

With no customer record, it answers `200` with `customer: null` and an empty list.

`GET /watchdog-scans` lists security scans of your targets, newest first. Each has `id`, `targetId`, `status`, `scanType`, `createdAt` and `completedAt`. Pass `targetId` for one target's scans. With no customer record, the list is empty.

## A customer's Watchdog targets

`GET /customers/{customerId}/watchdog-targets` lists the customer's targets, newest first. Each has its settings (`domain`, `displayName`, `targetUrl`, `checkType`, `checkIntervalSeconds`, `timeoutSeconds`, `regions`, `uptimeEnabled`, `securityEnabled`, `alertingEnabled`, `scanFrequency`, `latencyWarningMs`, `latencyCriticalMs`, `source`), its latest scan (`latestGrade`, `latestScore`, `lastScanAt`, `nextScanAt`), and `status`: `isUp`, `lastCheckAt`, `uptime24h`, `uptime7d`, `uptime30d`, `avgLatencyMs`, `sslDaysUntilExpiry` and `sslExpiryDate`.

`POST /customers/{customerId}/watchdog-targets` adds a target and answers `201` with it. Only `domain` is required, a public hostname; a customer can have each domain once.

```json
{ "domain": "example.com", "displayName": "Example", "scanFrequency": "daily" }
```

| Field | Default |
| --- | --- |
| `targetUrl` | `https://{domain}` |
| `uptimeEnabled`, `securityEnabled` | `true` |
| `checkType` | `https`; or `http`, `tcp`, `dns`, `icmp` |
| `checkIntervalSeconds` | 60; 30 to 3600 |
| `timeoutSeconds` | 10; 5 to 60 |
| `regions` | The offered ones of `nyc`, `lon` and `sgp` |
| `latencyWarningMs`, `latencyCriticalMs` | 2000 and 5000 |
| `scanFrequency` | `daily`; or `hourly`, `weekly` |

## A customer's Watchdog scans

`GET /customers/{customerId}/watchdog-scans` lists security scans, newest first. Pass `targetId` for one target. Each scan has `id`, `targetId`, `target` (`id`, `domain`, `displayName`), `status`, `scanType`, `triggeredBy`, `grade`, `totalScore`, `scoreChange`, `findings` (counts of `critical`, `high`, `medium`, `low`, `info`), `newFindingsCount`, `resolvedFindingsCount`, `startedAt`, `completedAt` and `durationMs`.

`POST /customers/{customerId}/watchdog-scans` queues a scan of one target and answers `202`:

```json
{ "operationId": "3f1c2a9e-8b7d-4c6e-9f10-2a3b4c5d6e7f", "targetId": "…", "scanType": "full" }
```

`operationId` is a UUID you choose; it becomes the scan ID, and retrying with the same one never starts a second scan. `scanType` is `full` (the default) or `quick`. The answer is `{ "operationId": "…", "scanId": "…", "status": "queued" }`. The target must have security scanning on. Only one scan per target runs at a time; starting a second answers `409`.

## Uptime status

`GET /customers/{customerId}/monitoring/status` returns the current state of every uptime-enabled target:

| Field | Contents |
| --- | --- |
| `aggregate` | `totalTargets`, `upTargets`, `downTargets`, `unknownTargets`, `overallStatus` (`operational`, `partial_outage`, `major_outage` or `unknown`) and `avgUptime24h` |
| `targets` | Each target's `id`, `name`, `targetUrl`, `checkType`, `checkIntervalSeconds`, `regions`, `enabled` and `status` (`isUp`, `freshness`, `lastCheckAt`, uptimes, `avgLatencyMs`, SSL expiry and `currentAlertSeverity`) |
| `dataSource` | The metrics backend that answered, or `cache_only` |
| `metricsError` | `null`, or `not_configured` or `unavailable` when live metrics couldn't be read |
| `light` | Whether latency and SSL were skipped |

Send `light=true` to skip latency and SSL. Answers may be up to 30 seconds old. A metrics outage still answers `200`: check `metricsError`.

`GET /customers/{customerId}/monitoring/targets` lists the customer's monitoring targets and their check settings, newest first.

## Uptime and latency history

`GET /customers/{customerId}/monitoring/history` returns uptime and latency over time.

| Parameter | Description |
| --- | --- |
| `range` | `24h`, `7d` or `30d`; default `7d` |
| `region` | One probe region, for example `nyc` or `lon` |
| `targetId` | Only this target |

The answer has `aggregatedUptime` (percentages) and `aggregatedLatency` (milliseconds), each a list of `{ "timestamp": …, "value": … }` points with `timestamp` in epoch milliseconds; `regionLatency` by region; `targets`, the series of the first five targets with data; `targetsMeta` (each target's `id`, `domain` and `displayName`); `regions`, `dataSource`, `hasData` and `partial`.

## Metrics for targets

`GET /monitoring/metrics?targetIds=<uuid>&targetIds=<uuid>` returns current metrics for 1 to 50 targets; repeat `targetIds` for each. Every target must belong to a customer you can read, or the whole request is refused.

Each entry in `metrics` has `targetId`, `uptime` (`isUp`, `uptime24h`, `uptime7d`, `uptime30d`, `lastCheckAt`), `latency` (`avgMs`, `p50Ms`, `p95Ms`, `p99Ms`) and `ssl` (`expiryDate`, `daysUntilExpiry`, `issuer`). Each part is `null` when there's no data.

## Incidents

`GET /customers/{customerId}/incidents` lists monitoring incidents, newest first: each run of one monitor's alerts, from the first alert to its recovery. `windowDays` sets how far back to look, 1 to 90 (default 30). Each incident has `key`, `monitorName`, `category`, `severity` (`warning` or `critical`), `status` (`open` or `resolved`), `region`, `targetId`, `startedAt`, `resolvedAt`, `lastTransition`, `eventCount`, `events` and `acknowledgement`.

`POST /customers/{customerId}/incidents/{incidentId}/acknowledge` records "I've got this" on an incident for everyone. `incidentId` is the incident's `key` or any of its event IDs. The body is optional: `{ "note": "…" }`, up to 500 characters. The first acknowledgement wins; a repeat returns it with `created: false`.

## Probe health

`GET /api/monitoring/probes/health` reports the health of Vigilbase's monitoring probes by region: `data.probes` (each with `region`, `provider`, `healthy`, `status`, `observed_at`) and counts of healthy, unhealthy and unknown probes. Use it to tell whether a gap in your history comes from a probe region.

## Older paths

Each v1 operation here also answers at an older path on `https://one.vigilbase.com/api`, such as `GET /api/customers/{id}/watchdog/targets` for `GET /customers/{customerId}/watchdog-targets`. The older paths are deprecated aliases and will be retired with `410 Gone`. Each operation's page in the [API reference](https://docs.vigilbase.com/one/api/reference) names its older path. See [hosts](https://docs.vigilbase.com/one/api#hosts).