---
title: "List Monitors"
method: GET
path: "/v1/monitors"
tags: ["Monitors"]
---

# List Monitors

`GET /v1/monitors`

## Request

- Base URL: `https://api.fettle.sh` (the document declares no server; this is the origin it was published from)
- URL: `https://api.fettle.sh/v1/monitors`
- Auth: API key in header `Authorization`

List monitors for the active organization.

Filter by search text, by type and by status (repeat a parameter to allow
several values), and by tags: with `tag_match=all` (default) a monitor must
carry every tag given, with `tag_match=any` at least one. Problems come
first by default; `sort=ssl_expiry` puts the soonest-expiring certificates
first. `view=compact` returns short rows without configuration or uptime
history.

## Query parameters

- `q` string, nullable
- `sort` 'status' | 'up_first' | 'name' | 'newest' | 'oldest' | 'ssl_expiry': Ordering options for the monitors list endpoint. ``STATUS`` is the default and surfaces actionable monitors first (PENDING → DOWN → DEGRADED → UP → PAUSED), then by name, then newest. ``UP_FIRST`` inverts the severity so healthy monitors lead. ``NAME``, ``NEWEST`` and ``OLDEST`` are plain orderings. ``SSL_EXPIRY`` orders by certificate expiry, soonest first; monitors with no known expiry (non-SSL types, not yet probed) come last.
- `tag` string[], nullable
- `tag_match` 'all' | 'any': How a multi-tag filter combines: every tag (``ALL``) or any of them.
- `type` CheckType[], nullable
- `status` MonitorStatus[], nullable
- `view` 'full' | 'compact': Shape of a monitors-list page: the full card or a compact row.
- `page` integer
- `size` integer

## Headers

- `X-Organization-Id` string, uuid, nullable

## Response `200`

A page of monitors: full rows by default, compact rows for `view=compact`.

- union
  - PaginatedResponseMonitorListRead
    - `items` MonitorListRead[], required
      - `id` string, uuid, required
      - `user_id` string, uuid, required
      - `name` string, required
      - `type` 'HTTP' | 'PING' | 'SSL' | 'TCP' | 'DNS', required: Type of probe a worker must run for a :class:`CheckJob`.
      - `target` string, required
      - `interval_seconds` integer, required
      - `timeout_seconds` integer, required
      - `regions` string[], required
      - `config` object, required
      - `status` 'PENDING' | 'UP' | 'DEGRADED' | 'DOWN' | 'PAUSED', required: Aggregated state of a monitor as derived by the results state machine.
      - `last_checked_at` string, date-time, nullable, required
      - `next_run_at` string, date-time, nullable, required
      - `confirmation_threshold` integer, required
      - `notification_cooldown_seconds` integer, required
      - `ssl_expires_at` string, date-time, nullable, required
      - `ssl_cert_info` SslCertInfo: Latest TLS certificate snapshot for an SSL monitor (У8). Promoted from an SSL probe's ``CheckResult.details`` onto the monitor row so the card/detail render "what cert, valid until, issued by/when" without a per-check query. All fields are nullable — a partial worker blob or a not-yet-probed monitor leaves them ``None``. ``not_before`` / ``not_after`` are kept as the raw RFC3339 strings the worker reported (display echo). The canonical, typed expiry is the monitor's top-level ``ssl_expires_at``; "expires in N days" is recomputed client-side from it, never the worker's stale ``days_left``.
        - `issuer` string, nullable
        - `subject` string, nullable
        - `not_before` string, nullable
        - `not_after` string, nullable
        - `valid` boolean, nullable
      - `is_active` boolean, required
      - `badge_enabled` boolean
      - `tags` string[]
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
      - `channel_ids` string[]
      - `uptime_daily` UptimeDayPoint[]
        - `date` string, date, required
        - `uptime_percentage` number, nullable, required
        - `total_checks` integer, required
        - `up_checks` integer, required
        - `down_checks` integer, required
        - `degraded_checks` integer
        - `maintenance_checks` integer
      - `region_statuses` RegionStatusRead[], required: Per-region latest status, sorted by region name. Built from ``region_snapshots``; ``job_id`` is dropped (internal dedup key) and malformed/partial snapshot rows are skipped rather than failing the read.
        - `region` string, required
        - `status` 'UP' | 'DEGRADED' | 'DOWN' | 'ERROR', required: Outcome of a single probe execution reported in a :class:`CheckResult`. ``DEGRADED`` means the resource responded / is working but in a degraded state (e.g. partial ping packet loss, a TLS cert expiring soon). It counts as up for uptime — it never penalises uptime% and never opens an incident — but is tracked separately so the UI can render it distinctly.
        - `checked_at` string, date-time, required
        - `display_name` string, required
    - `total` integer, required
    - `page` integer, required
    - `size` integer, required
    - `pages` integer, required
  - PaginatedResponseMonitorCompactRead
    - `items` MonitorCompactRead[], required
      - `id` string, uuid, required
      - `name` string, required
      - `type` 'HTTP' | 'PING' | 'SSL' | 'TCP' | 'DNS', required: Type of probe a worker must run for a :class:`CheckJob`.
      - `target` string, required
      - `status` 'PENDING' | 'UP' | 'DEGRADED' | 'DOWN' | 'PAUSED', required: Aggregated state of a monitor as derived by the results state machine.
      - `is_active` boolean, required
      - `tags` string[]
      - `interval_seconds` integer, required
      - `ssl_expires_at` string, date-time, nullable, required
      - `last_checked_at` string, date-time, nullable, required
    - `total` integer, required
    - `page` integer, required
    - `size` integer, required
    - `pages` integer, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/fettle/apis/fettle-sh.md) · [All operations](https://skmtc.dev/fettle/apis/fettle-sh/llms.txt) · [OpenAPI document](https://skmtc.dev/fettle/apis/fettle-sh/revisions/f32c8a18606f?raw)