---
title: "Update a metric alarm"
method: PATCH
path: "/orgs/{org_id}/alarms/{alarm_id}"
tags: ["alarms"]
---

# Update a metric alarm

`PATCH /orgs/{org_id}/alarms/{alarm_id}`

Update alarm thresholds, evaluation settings, or enabled state.

`clear_threshold` is the one field where `null` differs from omitting the key: send `null` to drop the hysteresis, omit it to leave it as is. It is validated against the resulting `threshold` and `comparison`, so patching either side of the pair alone can't invert them.

`metric_name` and `denominator_metric_name` are not patchable: changing what an alarm watches would leave its state and history describing a different question, so define a new alarm instead.

`enabled: true` requires at least one attached channel. Channels may be detached freely while an alarm is disabled, so this is what stops that from re-enabling an alarm that evaluates and records transitions with nowhere to notify.

The alarm's owning project is not patchable either, so the permission needed here is fixed for the life of the alarm: `alarms.manage` when it is org-level, `projects.alarms.manage` on the owner when it is not.

## Path parameters

- `org_id` string, required
- `alarm_id` string, required

## Request body

- UpdateAlarmReq — Body for **PATCH** `/orgs/{org_id}/alarms/{alarm_id}` — all fields optional.
  - `clear_threshold` number, double, nullable — Double-option so `null` clears the hysteresis and an absent key leaves it alone — a plain `Option` can't tell those apart.
  - `comparison` 'gt' | 'gte' | 'lt' | 'lte'
  - `datapoints_to_alarm` integer, nullable
  - `enabled` boolean, nullable
  - `evaluation_periods` integer, nullable
  - `min_sample_count` integer, nullable
  - `missing_data` 'not_breaching' | 'breaching' | 'insufficient' | 'ignore'
  - `name` string, nullable
  - `period_seconds` integer, nullable
  - `stat` string — Aggregation applied to each evaluation period. Percentiles run from p0.1 to p99.9 in tenths; equivalent spellings such as p95.0 are accepted and returned canonically as p95, while a finer value such as p95.05 is rejected rather than rounded. They are exact rather than interpolated from bins, so they are only available on app.run.duration_ms and cannot be used with denominator_metric_name.
  - `threshold` number, double, nullable

## Response `204`

Alarm updated

- unknown

## Other responses

- `400` — Bad request
- `403` — Forbidden
- `404` — Not found

## Changes

- **2026-07-28** `dd7e398ce0d3` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/timbal-ai/apis/timbal-platform-api/changes/orgs/:org_id/alarms/:alarm_id/patch.md)

---

[API](https://skmtc.dev/timbal-ai/apis/timbal-platform-api.md) · [All operations](https://skmtc.dev/timbal-ai/apis/timbal-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/timbal-ai/timbal-platform-api/revisions/dd7e398ce0d3/schema)