> ## 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.

# Findings API

> List anomaly findings, read their hourly evaluations and evidence, mute them, and set which anomalies open incidents.

A finding is one deviation of one series (signal, service, and environment) from its expected band.
Squasher checks every service hourly against its own history. Anomalies are findings with
`source_kind` set to `anomaly`. See [Anomalies and findings](/features/anomalies) for how the band
and resolution work.

## Operations

| Operation | Method and path | Purpose |
| - | - | - |
| `findings.list` | `GET /v1/projects/{project_id}/findings` | List findings, newest `last_seen_at` first, with a cursor. |
| `findings.get` | `GET /v1/projects/{project_id}/findings/{finding_id}` | Get one finding with its evaluations, hourly series, and evidence. |
| `findings.mute` | `POST /v1/projects/{project_id}/findings/{finding_id}/mute` | Stop a finding from opening an incident until a time, or unmute it. |
| `findings.getAnomalyPolicy` | `GET /v1/projects/{project_id}/anomaly-policy` | Read the project's anomaly policy. |
| `findings.updateAnomalyPolicy` | `PATCH /v1/projects/{project_id}/anomaly-policy` | Change any subset of the policy. |

Reads need `findings:read`. `findings.mute` and `findings.updateAnomalyPolicy` need
`findings:write`. A key with the `read` or `write` shortcut has them.

## List findings

```bash theme={null}
curl "https://api.squasher.ai/v1/projects/$SQUASHER_PROJECT_ID/findings?kind=anomaly&status=open&limit=50" \
  -H "Authorization: Bearer $SQUASHER_API_KEY"
```

| Query parameter | Values |
| - | - |
| `status` | `open` (the default), `resolved`, or `all`. |
| `kind` | `anomaly`. Other source kinds are reserved. |
| `signal` | `latency_p95`, `error_rate`, `traffic_drop`, `error_logs`, or `traffic`. |
| `service` | A service name. |
| `environment` | An environment name, for example `production`. |
| `severity` | `warning` or `critical`. |
| `from`, `to` | ISO times. Returns findings that were active at any point in that range. |
| `limit` | 1 to 100. The default is 50. |
| `cursor` | The `next_cursor` value of the previous page. |

The response is `{ "data": [Finding], "next_cursor": string | null }`. A finding has these fields:

| Field | Meaning |
| - | - |
| `signal`, `service`, `environment` | The series that left its band. `operation` names one route, or is `null`. |
| `detector` | `{ id, version }`: `hourly_baseline` (last 7 days) or `seasonal_hour_of_week`. |
| `status`, `resolved_at`, `resolved_reason` | `open` or `resolved`. The reason is `returned_to_band` or `corrected`. |
| `severity`, `score` | `warning` or `critical`. A larger score is further from normal; use it only to sort. |
| `observed`, `expected`, `unit`, `direction` | The latest breaching value, the band (`low`, `high`, `baseline`), the unit, and the side. |
| `first_seen_at`, `last_seen_at` | Start of the first and the latest hour outside the band. |
| `evaluation_count`, `window_seconds` | Hourly evaluations in the finding, and the evaluated window (3600). |
| `muted_until` | While in the future, the finding does not open an incident. |
| `incident` | `{ id, title, status }` of the incident this finding opened, or `null`. |
| `data_watermark` | Data newer than this was not complete at the last evaluation. |

`unit` is `ms`, `ratio` (a fraction from 0 to 1, such as an error rate), or `count`.

## Get one finding

`findings.get` returns `{ finding, evaluations, series, evidence }`:

* `evaluations`: each hourly evaluation, oldest first, with `observed`, the band, `breached`, and a
  `revision` that increases when late data changes an hour.
* `series`: hourly values from 24 hours before the finding started to its end (or now), at most 7
  days. Each point has the expected band of that hour.
* `evidence.deployments`: up to 10 deployments from 6 hours before the first breach to 1 hour after
  the last one.
* `evidence.error_groups`: up to 5 top issues of the service in that time.

A finding that is not in the project returns `404`.

## Mute a finding

```bash theme={null}
curl -X POST "https://api.squasher.ai/v1/projects/$SQUASHER_PROJECT_ID/findings/$FINDING_ID/mute" \
  -H "Authorization: Bearer $SQUASHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"until":"2026-10-20T00:00:00Z"}'
```

`until` must be in the future and at most 30 days ahead. Send `{"until": null}` to unmute. A mute
does not change the finding's status. The response is the updated finding.

## Anomaly policy

```json theme={null}
{
  "enabled": true,
  "timezone": "UTC",
  "recovery_buckets": 2,
  "incident_rules": [],
  "updated_at": null
}
```

| Field | Meaning |
| - | - |
| `enabled` | `false` turns off anomaly findings for the project. |
| `timezone` | IANA time zone. The seasonal check compares the same local hour of the week. |
| `recovery_buckets` | 1 to 24 hourly evaluations back inside the band before a finding resolves. |
| `incident_rules` | `[{ "signal": "*" or a signal, "min_severity": "warning" or "critical" }]`. Empty means no paging. |
| `updated_at` | `null` while the project uses the defaults. |

Anomalies do not open incidents by default. Send `incident_rules` with `findings.updateAnomalyPolicy`
to open an incident for the signals and severities you choose:

```bash theme={null}
curl -X PATCH "https://api.squasher.ai/v1/projects/$SQUASHER_PROJECT_ID/anomaly-policy" \
  -H "Authorization: Bearer $SQUASHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"incident_rules":[{"signal":"error_rate","min_severity":"warning"},{"signal":"*","min_severity":"critical"}]}'
```

An incident that a finding opens has the source type `finding` and uses the project's notification
routes and on-call paging.

## CLI and MCP

| Command | Operation |
| - | - |
| `squasher findings list --project <id> [--kind anomaly]` | `findings.list` |
| `squasher anomalies --project <id>` | `findings.list` with `kind=anomaly` |
| `squasher findings get --project <id> <finding_id>` | `findings.get` |
| `squasher findings mute --project <id> <finding_id> --until 2h` | `findings.mute` |
| `squasher findings unmute --project <id> <finding_id>` | `findings.mute` with `null` |
| `squasher anomalies policy get --project <id>` | `findings.getAnomalyPolicy` |
| `squasher anomalies policy set --project <id> --page error_rate:critical` | `findings.updateAnomalyPolicy` |

`policy set` also takes `--enabled`, `--timezone`, `--recovery-buckets`, and `--no-paging`. In MCP
Code Mode, call `search("findings")`.

Related: [Anomalies and findings](/features/anomalies), [Incidents API](/api-reference/incidents).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.