# List monitors

`GET https://evohub.io/api/v1/monitors`

Part of the [Uptime API](https://docs-dev.evohub.io/uptime.md) reference · operationId `listMonitors`.

Every monitor the caller can see, newest first. Each monitor carries
its 30-day uptime in `uptime_percent["30d"]` and `sla_breached_30d`
(heartbeat monitors carry neither) and, while a silence window mutes
it, `silenced_until`.

`data` is `[]` when there are no monitors.

Requires the `uptime:monitor:read` scope.

## Authorization

Any one of:

- `bearerKey`
- `headerKey`

Where:

- `bearerKey`: HTTP Bearer — An EvoHub API key (`evohub_…`) as a bearer token.
- `headerKey`: API key in the header `X-API-Key` — An EvoHub API key (`evohub_…`).

## Query parameters

- `team_id` (string, example `none`): Narrow to one team's monitors, or `none` for only the organization-wide ones. It never widens what the caller can see.

## Responses

### 200 — The monitors.

Content type: `application/json`

Type: `object`

- `data` (array of Monitor)
  - `id` (string): Starts with `mon_`.
  - `org_id` (string)
  - `team_id` (string): The owning team, or `""` for the whole organization.
  - `name` (string)
  - `url` (string): The target; `""` for a heartbeat monitor. Shown with credentials masked: userinfo becomes `****:****@` and the values of `token`, `key`, `secret`, `password`, `sig`, `signature`, `auth`, `api_key` and `access_token` query parameters (any case, or a name ending in `_` or `-` plus one of them) become `****`. Checks use the URL as entered.
  - `type` (MonitorType, one of `http`, `keyword`, `tcp`, `icmp`, `heartbeat`)
  - `interval_seconds` (integer): How often it is checked; for a heartbeat, how often a ping is expected.
  - `timeout_seconds` (integer)
  - `locations` (array of string): Probe locations. Empty means EvoHub chooses.
  - `keyword` (string): Text a `keyword` monitor looks for in the body.
  - `expected_status` (integer): The status code an HTTP check expects when there are no `status_code` assertions.
  - `is_active` (boolean): `false` while paused: no checks and no alerts.
  - `failure_threshold` (integer): Failed checks in a row before the monitor is down.
  - `consecutive_failures` (integer)
  - `last_checked_at` (string (date-time))
  - `last_status` (MonitorStatus, one of `up`, `down`, `degraded`, `unknown`)
  - `silenced_until` (string (date-time)): Present on the list while a silence window mutes the monitor; when it ends.
  - `http_method` (string)
  - `http_headers` (array of object): The request headers by name, sorted. A header's value is never returned, since it often carries a token. `has_value` says whether one is stored.
    - `name` (string)
    - `has_value` (boolean)
  - `http_body` (string)
  - `http_auth_user` (string)
  - `has_http_auth_password` (boolean): Whether a Basic Auth password is stored. The password itself is never returned.
  - `check_ssl` (boolean): Warn before the TLS certificate expires.
  - `ssl_expiry_threshold_days` (integer): Days before expiry to warn.
  - `ssl_expiry_days` (integer): Days until the certificate expires, from the last check.
  - `tags` (array of string)
  - `group_id` (string)
  - `response_time_threshold_ms` (integer)
  - `oncall_policy_id` (string): The On-Call escalation policy its alerts go to.
  - `re_alert_minutes` (integer): Minutes between repeat alerts while down.
  - `grace_seconds` (integer): Heartbeat only. How late a ping may be.
  - `ping_token` (string): Heartbeat only. The job calls `https://evohub.io/ping/{ping_token}`.
  - `last_ping_at` (string (date-time)): Heartbeat only.
  - `created_at` (string (date-time))
  - `updated_at` (string (date-time))
  - `assertions` (array of Assertion)
    - `type` (string, required, one of `status_code`, `body`, `json`, `header`)
    - `field` (string, max length 1024)
    - `operator` (string, required, one of `in`, `contains`, `not_contains`, `equals`, `not_equals`, `exists`)
    - `value` (string, max length 1024)
  - `degraded_threshold_ms` (integer | null): A passing check slower than this is degraded.
  - `alert_on_degraded` (boolean): Raise a lower-severity alert while degraded.
  - `consecutive_degraded` (integer)
  - `sla_target` (number | null): The uptime percentage the monitor is held to, e.g. 99.9.
  - `last_failure_reason` (string)
  - `last_failure_at` (string (date-time))
  - `uptime_percent` (object): Uptime percentage per window. A single monitor carries `24h`, `7d`, `30d` and `90d`; the list carries only `30d`. `null` for a window with no checks. Absent for heartbeat monitors.
    - Other keys: number | null
  - `sla_breached_30d` (boolean): The 30-day uptime is below `sla_target`. Absent without a target or 30-day data, and for heartbeat monitors.

### 401 — No API key was sent, or it is unknown, revoked or expired (`UNAUTHORIZED`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `MONITOR_NOT_FOUND`)
  - `message` (string, required, example `monitor not found`)
  - `request_id` (string)

### 403 — The key lacks the scope this endpoint needs (`FORBIDDEN`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `MONITOR_NOT_FOUND`)
  - `message` (string, required, example `monitor not found`)
  - `request_id` (string)

### 429 — Too many requests (`RATE_LIMITED`). Wait for `Retry-After` seconds.

Headers:

- `Retry-After` (integer): Seconds to wait before retrying.

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `MONITOR_NOT_FOUND`)
  - `message` (string, required, example `monitor not found`)
  - `request_id` (string)

### 500 — Something went wrong on EvoHub's side (`INTERNAL_ERROR`). Retry later.

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `MONITOR_NOT_FOUND`)
  - `message` (string, required, example `monitor not found`)
  - `request_id` (string)

## Example request

```bash
curl -X GET 'https://evohub.io/api/v1/monitors' \
  -H 'Authorization: Bearer <TOKEN>'
```