---
title: "PATCH /api/projects/{project_id}/platform_alerts/{id}/"
method: PATCH
path: "/api/projects/{project_id}/platform_alerts/{id}/"
tags: ["platform_alerts"]
---

# PATCH /api/projects/{project_id}/platform_alerts/{id}/

`PATCH /api/projects/{project_id}/platform_alerts/{id}/`

## Request

- Base URL: `https://us.posthog.com`
- URL: `https://us.posthog.com/api/projects/{project_id}/platform_alerts/{id}/`
- Auth: HTTP bearer

## Path parameters

- `id` string, required
- `project_id` string, required

## Request body

- union
  - PatchedInsightPlatformAlertConfigurationEdit: The settings an edit can change. Each source kind subclasses it with a typed `source_config`.
    - `source_kind` string: Product whose data the alert evaluates. It cannot change, so it must match the stored value.
    - `name` string: Human-readable name of the alert.
    - `enabled` boolean: Whether the alert is evaluated on schedule.
    - `source_config` InsightPlatformAlertSourceConfig
      - `insight_id` integer, required: The insight the alert checks. It cannot change through this API.
      - `condition` InsightPlatformAlertCondition, required
        - `threshold` InsightThreshold, required
          - `bounds` InsightsThresholdBounds
            - `lower` number, nullable: Alert fires when the value drops below this number.
            - `upper` number, nullable: Alert fires when the value exceeds this number.
          - `type` 'absolute' | 'percentage', required
        - `comparison` AlertCondition, required
          - `type` 'absolute_value' | 'relative_increase' | 'relative_decrease', required
        - `detector` unknown
    - `grouping` Grouping
      - `mode` 'single' | 'by_result_labels', required: * `single` - Single * `by_result_labels` - By result labels
      - `keys` string[]: Result labels whose values make a group, such as service_name. Empty for mode single, required for by_result_labels. Changing them deletes the existing instances and closes their notification threads without a message.
      - `max_instances` integer: Most instances the alert keeps at once. Groups past it are not tracked, and the last message says how many were left out.
      - `on_overflow` 'degrade_visible': * `degrade_visible` - Degrade visible
    - `schedule_restriction` AlertScheduleRestriction
      - `blocked_windows` AlertScheduleRestrictionWindow[], required: Blocked local time windows when the alert must not run. Overlapping or identical windows are merged when saved. At most five windows before normalization; empty array clears quiet hours.
        - `start` string, required: Start time HH:MM (24-hour, project timezone). Inclusive. Each window must span ≥ 30 minutes on the local daily timeline (half-open [start, end)).
        - `end` string, required: End time HH:MM (24-hour). Exclusive (half-open interval). Each window must span ≥ 30 minutes locally.
    - `evaluation_periods` integer: Number of recent checks considered when deciding to fire.
    - `datapoints_to_alarm` integer: Number of breaching checks within evaluation_periods required to fire. Cannot exceed evaluation_periods.
    - `cooldown_minutes` integer: Minimum minutes between notifications for the same alert.
  - PatchedLogsPlatformAlertConfigurationEdit: The settings an edit can change. Each source kind subclasses it with a typed `source_config`.
    - `source_kind` string: Product whose data the alert evaluates. It cannot change, so it must match the stored value.
    - `name` string: Human-readable name of the alert.
    - `enabled` boolean: Whether the alert is evaluated on schedule.
    - `source_config` LogsPlatformAlertSourceConfig
      - `filters` LogsAlertFilters, required
        - `filterGroup` PropertyGroupFilter
          - `type` 'AND' | 'OR', required
          - `values` PropertyGroupFilterValue[], required
            - `type` 'AND' | 'OR', required
            - `values` union[], required
              - …
        - `serviceNames` string[], nullable
        - `severityLevels` LogSeverityLevel[], nullable
      - `condition` LogsPlatformAlertCondition, required
        - `threshold_count` integer, required: Number of matching log entries in the window that breaches the threshold. Use 0 with the above operator to fire on any matching log.
        - `threshold_operator` 'above' | 'below', required
        - `window_minutes` 5 | 10 | 15 | 30 | 60, required
    - `grouping` Grouping
      - `mode` 'single' | 'by_result_labels', required: * `single` - Single * `by_result_labels` - By result labels
      - `keys` string[]: Result labels whose values make a group, such as service_name. Empty for mode single, required for by_result_labels. Changing them deletes the existing instances and closes their notification threads without a message.
      - `max_instances` integer: Most instances the alert keeps at once. Groups past it are not tracked, and the last message says how many were left out.
      - `on_overflow` 'degrade_visible': * `degrade_visible` - Degrade visible
    - `schedule_restriction` AlertScheduleRestriction
      - `blocked_windows` AlertScheduleRestrictionWindow[], required: Blocked local time windows when the alert must not run. Overlapping or identical windows are merged when saved. At most five windows before normalization; empty array clears quiet hours.
        - `start` string, required: Start time HH:MM (24-hour, project timezone). Inclusive. Each window must span ≥ 30 minutes on the local daily timeline (half-open [start, end)).
        - `end` string, required: End time HH:MM (24-hour). Exclusive (half-open interval). Each window must span ≥ 30 minutes locally.
    - `evaluation_periods` integer: Number of recent checks considered when deciding to fire.
    - `datapoints_to_alarm` integer: Number of breaching checks within evaluation_periods required to fire. Cannot exceed evaluation_periods.
    - `cooldown_minutes` integer: Minimum minutes between notifications for the same alert.

## Response `200`

- PlatformAlertConfiguration
  - `id` string, uuid, required: Unique identifier of the alert configuration.
  - `name` string, required: Human-readable name of the alert.
  - `enabled` boolean, required: Whether the alert is evaluated on schedule.
  - `source_kind` 'logs' | 'insight', required: * `logs` - Logs * `insight` - Insight
  - `source_config` object, required: Source-specific settings. The shape depends on source_kind. The bound the alert is evaluated against is under the condition key.
  - `check_interval_minutes` integer, required: Minutes between scheduled checks. Applies when recurrence_unit is null.
  - `recurrence_unit` union, required: Calendar unit the alert recurs on. Null means it recurs on check_interval_minutes. * `day` - Day * `week` - Week * `month` - Month
    - 'day' | 'week' | 'month': * `day` - Day * `week` - Week * `month` - Month
    - unknown
  - `anchor_time` string, nullable, required: Local time (HH:MM in the project timezone) a calendar recurrence lands on. Null means the default anchor for the unit.
  - `evaluation_periods` integer, required: Number of recent checks considered when deciding to fire.
  - `datapoints_to_alarm` integer, required: Number of breaching checks within evaluation_periods required to fire.
  - `cooldown_minutes` integer, required: Minimum minutes between notifications for the same alert.
  - `schedule_restriction` AlertScheduleRestriction, required
    - `blocked_windows` AlertScheduleRestrictionWindow[], required: Blocked local time windows when the alert must not run. Overlapping or identical windows are merged when saved. At most five windows before normalization; empty array clears quiet hours.
      - `start` string, required: Start time HH:MM (24-hour, project timezone). Inclusive. Each window must span ≥ 30 minutes on the local daily timeline (half-open [start, end)).
      - `end` string, required: End time HH:MM (24-hour). Exclusive (half-open interval). Each window must span ≥ 30 minutes locally.
  - `next_check_at` string, date-time, nullable, required: When the next check is due. Null when no check is scheduled.
  - `consecutive_failures` integer, required: Number of checks in a row that failed to evaluate.
  - `legacy_configuration_id` string, uuid, nullable, required: ID of the legacy source configuration this row was backfilled from. Null for alerts created on the platform.
  - `grouping` Grouping, required
    - `mode` 'single' | 'by_result_labels', required: * `single` - Single * `by_result_labels` - By result labels
    - `keys` string[]: Result labels whose values make a group, such as service_name. Empty for mode single, required for by_result_labels. Changing them deletes the existing instances and closes their notification threads without a message.
    - `max_instances` integer: Most instances the alert keeps at once. Groups past it are not tracked, and the last message says how many were left out.
    - `on_overflow` 'degrade_visible': * `degrade_visible` - Degrade visible
  - `snooze_until` string, date-time, nullable, required: Time until which every instance's notifications are muted. Null when not muted. An instance's own snooze_until mutes one group, and the later of the two holds.
  - `check_status` 'ok' | 'errored' | 'broken', required: * `ok` - OK * `errored` - Errored * `broken` - Broken
  - `overflowed_groups` integer, required: New groups the last successful check could not track because the alert already held grouping.max_instances instances. 0 when every group fit.
  - `overflow_is_lower_bound` boolean, required: Whether the last successful check cut its results before counting overflowed_groups. When true, more groups than overflowed_groups may be untracked.
  - `owner` 'source' | 'platform', required: * `source` - Source * `platform` - Platform
  - `created_at` string, date-time, required: When the configuration was created.
  - `updated_at` string, date-time, required: When the configuration was last changed.
  - `alerts` PlatformAlert[], required: Runtime state for each result group of this configuration.
    - `id` string, uuid, required: Unique identifier of this alert instance.
    - `grouping_key` string, required: Key of the result group this instance tracks. Empty when the source does not group results.
    - `state` 'not_firing' | 'firing' | 'errored' | 'snoozed' | 'broken', required: * `not_firing` - Not firing * `firing` - Firing * `errored` - Errored * `snoozed` - Snoozed * `broken` - Broken
    - `firing_started_at` string, date-time, nullable, required: When the current firing started. Null when the instance is not firing.
    - `last_notified_at` string, date-time, nullable, required: When a notification was last sent for this instance.
    - `snooze_until` string, date-time, nullable, required: Time until which notifications are snoozed. Null when not snoozed.
    - `labels` object, required: Result labels and their values for the group this instance tracks, such as {"service_name": "checkout"}. Empty when the source does not group results.

## Other responses

- `403`: The caller cannot write alerts of this source kind.
- `404`: No alert with this id that the caller can read.
- `409`: The source product owns this alert, so only its own API edits it.

## Changes

> 53 revisions in range; 1 not diffed.

- **2026-10-22** `bab3bb4f0c72`: 6 info
  - added `insight` mapping keys to the request discriminator (media type: application/json)
  - added `insight` mapping keys to the request discriminator (media type: application/x-www-form-urlencoded)
  - added `insight` mapping keys to the request discriminator (media type: multipart/form-data)
  - added `#/components/schemas/PatchedInsightPlatformAlertConfigurationEdit` to the request body `oneOf` list (media type: application/json)
  - …2 more
- **2026-10-20** `a83201bb9b6a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/posthog/apis/posthog-api/changes/api/projects/:project_id/platform_alerts/:id/patch.md)

---

[API](https://skmtc.dev/posthog/apis/posthog-api.md) · [All operations](https://skmtc.dev/posthog/apis/posthog-api/llms.txt) · [OpenAPI document](https://skmtc.dev/posthog/apis/posthog-api/revisions/993f70ab941b?raw)