alerts

post/api/projects/{project_id}/alerts/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/alerts/
  • Auth: HTTP bearer

Path parameters

project_idstring required

Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request body

idstring uuid required
created_atstring date-time required
insightinteger required

Insight ID monitored by this alert. Note: Response returns full InsightBasicSerializer object.

insight_short_idstring required

Short ID of the insight monitored by this alert.

insight_display_namestring required

Display name of the insight monitored by this alert.

llm_detector_availableboolean nullable required

Whether this alert can use the AI detector, judged for the person who created it, since scheduled checks run as the creator. Only computed when retrieving a single alert; null elsewhere.

namestring

Human-readable name for the alert.

subscribed_usersinteger[] required

User IDs to subscribe to this alert. Note: Response returns full UserBasicSerializer object.

statestring required

Current alert state: Firing, Not firing, Errored, or Snoozed.

enabledboolean

Whether the alert is actively being evaluated.

last_notified_atstring date-time nullable required
last_checked_atstring date-time nullable required
schedule_start_timestring nullable

Local time that starts alert checks in HH:MM format. Updating this value recalculates the next check. Set null to remove the custom start time.

next_check_atstring date-time nullable required
checks_totalinteger nullable required

Total alert checks matching the retrieve filters (date window). Only set on alert retrieve; omitted otherwise.

evaluation_delay_intervalsinteger

Skip this many completed insight intervals after excluding the ongoing interval (0-100, default 0). Time-series Trends only. A positive delay requires check_ongoing_interval=false. Uses the insight interval, not the check frequency. Allows late data to arrive, but also delays detection of real problems.

calculation_interval'real_time' | 'every_15_minutes' | 'hourly' | 'daily' | 'weekly' | 'monthly'
  • real_time - real_time
  • every_15_minutes - every_15_minutes
  • hourly - hourly
  • daily - daily
  • weekly - weekly
  • monthly - monthly
snoozed_untilstring nullable

Snooze the alert until this time. Pass a relative date string (e.g. '2h', '1d') or null to unsnooze.

skip_weekendboolean nullable

Skip alert evaluation on weekends (Saturday and Sunday, local to project timezone).

last_valuenumber double nullable required

The last calculated value from the most recent alert check.

investigation_agent_enabledboolean

When enabled, an investigation agent runs on each check where the alert fires, up to three times per firing episode, and writes findings to a Notebook linked from the alert check. An episode is the run of consecutive firing checks since the last check that did not fire. A later investigation of the same episode that reaches a different verdict sends one follow-up notification, unless investigation_inconclusive_action suppresses it. Only effective for detector-based (anomaly) alerts.

investigation_gates_notificationsboolean

When enabled (and investigation_agent_enabled is on), the first fire of an episode is held until the investigation agent produces a verdict, and that notification is suppressed when the verdict is false_positive (and optionally when inconclusive). Later fires of the same episode notify without waiting. A safety-net task force-fires after a few minutes if the investigation stalls.

investigation_inconclusive_action'notify' | 'suppress'
  • notify - Notify
  • suppress - Suppress

Response

idstring uuid required
created_atstring date-time required
insightinteger required

Insight ID monitored by this alert. Note: Response returns full InsightBasicSerializer object.

insight_short_idstring required

Short ID of the insight monitored by this alert.

insight_display_namestring required

Display name of the insight monitored by this alert.

llm_detector_availableboolean nullable required

Whether this alert can use the AI detector, judged for the person who created it, since scheduled checks run as the creator. Only computed when retrieving a single alert; null elsewhere.

namestring

Human-readable name for the alert.

subscribed_usersinteger[] required

User IDs to subscribe to this alert. Note: Response returns full UserBasicSerializer object.

statestring required

Current alert state: Firing, Not firing, Errored, or Snoozed.

enabledboolean

Whether the alert is actively being evaluated.

last_notified_atstring date-time nullable required
last_checked_atstring date-time nullable required
schedule_start_timestring nullable

Local time that starts alert checks in HH:MM format. Updating this value recalculates the next check. Set null to remove the custom start time.

next_check_atstring date-time nullable required
checks_totalinteger nullable required

Total alert checks matching the retrieve filters (date window). Only set on alert retrieve; omitted otherwise.

evaluation_delay_intervalsinteger

Skip this many completed insight intervals after excluding the ongoing interval (0-100, default 0). Time-series Trends only. A positive delay requires check_ongoing_interval=false. Uses the insight interval, not the check frequency. Allows late data to arrive, but also delays detection of real problems.

calculation_interval'real_time' | 'every_15_minutes' | 'hourly' | 'daily' | 'weekly' | 'monthly'
  • real_time - real_time
  • every_15_minutes - every_15_minutes
  • hourly - hourly
  • daily - daily
  • weekly - weekly
  • monthly - monthly
snoozed_untilstring nullable

Snooze the alert until this time. Pass a relative date string (e.g. '2h', '1d') or null to unsnooze.

skip_weekendboolean nullable

Skip alert evaluation on weekends (Saturday and Sunday, local to project timezone).

last_valuenumber double nullable required

The last calculated value from the most recent alert check.

investigation_agent_enabledboolean

When enabled, an investigation agent runs on each check where the alert fires, up to three times per firing episode, and writes findings to a Notebook linked from the alert check. An episode is the run of consecutive firing checks since the last check that did not fire. A later investigation of the same episode that reaches a different verdict sends one follow-up notification, unless investigation_inconclusive_action suppresses it. Only effective for detector-based (anomaly) alerts.

investigation_gates_notificationsboolean

When enabled (and investigation_agent_enabled is on), the first fire of an episode is held until the investigation agent produces a verdict, and that notification is suppressed when the verdict is false_positive (and optionally when inconclusive). Later fires of the same episode notify without waiting. A safety-net task force-fires after a few minutes if the investigation stalls.

investigation_inconclusive_action'notify' | 'suppress'
  • notify - Notify
  • suppress - Suppress

Changes

No recorded changes to this operation across all 1 revision of this API.