> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitors API

> List, create, upsert, inspect, update, and delete uptime and heartbeat monitors.

Use the Monitors API for status checks that can feed incidents, status pages, and operator summaries.

## Operations

| Operation                       | Method and path                                                       | Purpose                                                                                          |
| ------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `monitors.list`                 | `GET /v1/projects/{project_id}/monitors`                              | List monitors with filters for kind, status, enabled state, and search text.                     |
| `monitors.listTemplates`        | `GET /v1/projects/{project_id}/monitor-templates`                     | List one-click monitor templates and their required inputs.                                      |
| `monitors.create`               | `POST /v1/projects/{project_id}/monitors`                             | Create a monitor with `{ name, kind, target, config, enabled?, linkedComponent?, runbookUrl? }`. |
| `monitors.createFromTemplate`   | `POST /v1/projects/{project_id}/monitor-templates/{template_id}`      | Create a monitor from a template by sending template input values.                               |
| `monitors.upsertByName`         | `POST /v1/projects/{project_id}/monitors/upsert`                      | Create or update a monitor by name for declarative workflows.                                    |
| `monitors.listEvaluations`      | `GET /v1/projects/{project_id}/monitors/evaluations`                  | Latest noise evaluation per monitor, with a recommendation and the evidence behind it.           |
| `monitors.getTuningSettings`    | `GET /v1/projects/{project_id}/monitors/tuning`                       | Project tuning mode, spend guardrails, adjustment trail, and measured outcomes.                  |
| `monitors.updateTuningSettings` | `PATCH /v1/projects/{project_id}/monitors/tuning`                     | Configure bounded project tuning and opt into auto mode.                                         |
| `monitors.getTuning`            | `GET /v1/projects/{project_id}/monitors/{monitor_id}/tuning`          | Declared versus effective config and adjustment history.                                         |
| `monitors.updateTuning`         | `PATCH /v1/projects/{project_id}/monitors/{monitor_id}/tuning`        | Override tuning mode for one monitor.                                                            |
| `monitors.tuningAction`         | `POST /v1/projects/{project_id}/monitors/{monitor_id}/tuning/actions` | Investigate, apply, reject, or revert an adjustment.                                             |
| `monitors.get`                  | `GET /v1/projects/{project_id}/monitors/{monitor_id}`                 | Get one monitor with latest state and linked incident.                                           |
| `monitors.update`               | `PATCH /v1/projects/{project_id}/monitors/{monitor_id}`               | Update monitor metadata, target, config, enabled state, linked component, or runbook.            |
| `monitors.delete`               | `DELETE /v1/projects/{project_id}/monitors/{monitor_id}`              | Delete a monitor.                                                                                |

Monitor `kind` values include checks such as HTTP, SSL, TCP, and heartbeat. The `config` object is kind-specific; use OpenAPI or MCP search for the current schema before writing. For common detector classes, list monitor templates and call `createFromTemplate` with the returned input keys.

## Monitor noise evaluations

Squasher evaluates enabled monitors every hour to score whether they are earning their interruptions, and exposes the result through `monitors.listEvaluations`. Each row reports how many incidents the monitor opened over the trailing window, how many of those actually reached a human, how many anyone acted on, how many cleared on their own, and the median time they stayed open — plus a `recommendation` and a plain-language `rationale`.

| Recommendation      | Meaning                                                                               |
| ------------------- | ------------------------------------------------------------------------------------- |
| `no_change`         | Either people act on it, or there is not enough evidence to say anything.             |
| `widen_threshold`   | Frequent, short-lived, and ignored — raise `failureThreshold` so it must persist.     |
| `demote_attention`  | Ignored and transient but infrequent — route it to a digest instead of a pager.       |
| `redefine`          | Ignored incidents that stay open for hours; a threshold change would only delay them. |
| `disable_candidate` | Nothing responds and it does not clear on its own — confirm it still has an owner.    |

Every conclusion is scoped to incidents whose opening alert produced a successful notification delivery (`delivered_count`), so a broken notification route can never be misread as an unwanted monitor. Check `confidence` before acting — `low` means the sample does not support a change.

## Agent-driven tuning

Tuning defaults to `recommend`. The hourly watcher uses monitor history, telemetry, notification delivery, and engineering-response signals to investigate current candidates. Before suggesting a threshold change, it replays historical checks and rejects any proposal that would have missed an incident associated with an engineering response.

The monitors dashboard is the recommendation inbox: safe threshold or attention fixes can be applied in one click, while target, query, severity, disable, and code changes always remain human-owned. Attention fixes fail closed unless a monitor-specific digest route can deliver every opened incident through an enabled supported destination. Slack incident messages link to the same evidence and approval control. Slack buttons never mutate configuration through a `GET`.

For every effective threshold override, Squasher compares equal before-and-after observation windows and reports `outcomes` plus `outcome_summary` from `monitors.getTuningSettings`. Outcomes remain `pending` until enough evidence arrives, and then resolve to `beneficial`, `neutral`, `harmful`, or `insufficient_data`. A change cannot be counted as beneficial when engineering-response signals increase. Attention-routing changes remain `insufficient_data` until interruption-delivery outcomes are available.

Modes are `off`, `recommend`, and `auto`, at both project and monitor scope. Turning tuning off immediately reverts active overrides. Auto mode is deliberately narrow: it can only widen `failureThreshold`, never disable a monitor or rewrite its target, query, severity, or declared config. The effective override is separate, visible, reversible, and expires after 1–30 days. A real monitor edit permanently locks tuning and immediately reverts an active override; an identical declarative `upsertByName` sync is a no-op and does not lock it.

Project settings include daily budget, per-investigation budget, and daily investigation limits. Defaults are $1 per project per day, $0.25 per investigation, and five investigations per day. The accepted maxima are $5 per project per day, $0.50 per investigation, and 20 investigations per day. Reaching a configured limit pauses new investigations without interrupting monitor execution or existing alerts.

## CLI and MCP

Use `squasher monitors ...` for terminal workflows. `squasher monitors evaluate --project <project_id> --actionable` shows live recommendations. `squasher monitors tuning show --project <project_id> <monitor_id>` shows declared and effective config; `tuning configure`, `tuning investigate`, and `tuning act` control the bounded workflow. In MCP Code Mode, call `search("monitor tuning")`. Treat tuning writes as confirmation-required.

## Agent handoff

```text theme={null}
Review Squasher monitors for project <project_id>. List monitors with q/kind/status/enabled filters, inspect the relevant monitor, and connect findings to incidents or status-page components. Ask before changing monitor config or deleting any monitor.
```

Related: [Status monitoring](/features/status-monitoring), [Status pages API](/api-reference/status-pages).