Alerts

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

`GET`
`POST`
`GET`
`PATCH`
`DELETE`
`POST`
`POST`
`POST`
`POST`

List all alerts

Also available via the PostHog MCP server:
alerts-list — List alerts

Required API key scopes

alert:read

Query parameters

created_by
string
has_detector
boolean
insight_id
integer
insight_tag
string
limit
integer
offset
integer
search
string

Response

Example request

GET /api/projects/:project_id/alerts
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/alerts/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/alerts/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "created_at": "2019-08-24T14:15:22Z",
      "insight": 0,
      "insight_short_id": "string",
      "insight_display_name": "string",
      "name": "string",
      "subscribed_users": [
        0
      ],
      "threshold": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "created_at": "2019-08-24T14:15:22Z",
        "name": "string",
        "configuration": {
          "bounds": null,
          "type": "absolute"
        }
      },
      "condition": {
        "type": "absolute_value"
      },
      "state": "string",
      "enabled": true,
      "last_notified_at": "2019-08-24T14:15:22Z",
      "last_checked_at": "2019-08-24T14:15:22Z",
      "schedule_start_time": "string",
      "next_check_at": "2019-08-24T14:15:22Z",
      "checks": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "created_at": "2019-08-24T14:15:22Z",
          "calculated_value": 0,
          "state": "Firing",
          "error": {
            "property1": "string",
            "property2": "string"
          },
          "targets_notified": true,
          "anomaly_scores": null,
          "triggered_points": null,
          "triggered_dates": null,
          "interval": "string",
          "triggered_metadata": null,
          "investigation_status": "pending",
          "investigation_verdict": "true_positive",
          "investigation_summary": "string",
          "investigation_notebook_short_id": "string",
          "notification_sent_at": "2019-08-24T14:15:22Z",
          "notification_suppressed_by_agent": true,
          "deliveries": [
            {
              "channel": "string",
              "target": "string",
              "target_id": "string",
              "template": "string",
              "status": "string",
              "at": "2019-08-24T14:15:22Z",
              "display_label": "string"
            }
          ]
        }
      ],
      "checks_total": 0,
      "config": {
        "check_ongoing_interval": null,
        "series_index": 0,
        "type": "TrendsAlertConfig"
      },
      "detector_config": {
        "detectors": [
          {
            "preprocessing": null,
            "threshold": null,
            "type": "zscore",
            "window": null
          }
        ],
        "operator": "and",
        "type": "ensemble"
      },
      "calculation_interval": "real_time",
      "snoozed_until": "string",
      "skip_weekend": true,
      "schedule_restriction": {
        "blocked_windows": [
          {
            "start": "string",
            "end": "string"
          }
        ]
      },
      "last_value": 0,
      "investigation_agent_enabled": true,
      "investigation_gates_notifications": true,
      "investigation_inconclusive_action": "notify",
      "search_match_type": "exact"
    }
  ]
}

Create alerts

Required API key scopes

alert:write

Request parameters

insight
integer
name
string
subscribed_users
array
threshold
condition
enabled
boolean
schedule_start_time
stringnull
config
detector_config
calculation_interval
snoozed_until
stringnull
skip_weekend
booleannull
schedule_restriction
investigation_agent_enabled
boolean
investigation_gates_notifications
boolean
investigation_inconclusive_action

Response

Example request

POST /api/projects/:project_id/alerts
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/alerts/\
	-d insight="integer",\
	-d subscribed_users="array",\
	-d threshold=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/alerts/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"insight": "integer",
		"subscribed_users": "array"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "insight": 0,
  "insight_short_id": "string",
  "insight_display_name": "string",
  "name": "string",
  "subscribed_users": [
    0
  ],
  "threshold": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "created_at": "2019-08-24T14:15:22Z",
    "name": "string",
    "configuration": {
      "bounds": null,
      "type": "absolute"
    }
  },
  "condition": {
    "type": "absolute_value"
  },
  "state": "string",
  "enabled": true,
  "last_notified_at": "2019-08-24T14:15:22Z",
  "last_checked_at": "2019-08-24T14:15:22Z",
  "schedule_start_time": "string",
  "next_check_at": "2019-08-24T14:15:22Z",
  "checks": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "created_at": "2019-08-24T14:15:22Z",
      "calculated_value": 0,
      "state": "Firing",
      "error": {
        "property1": "string",
        "property2": "string"
      },
      "targets_notified": true,
      "anomaly_scores": null,
      "triggered_points": null,
      "triggered_dates": null,
      "interval": "string",
      "triggered_metadata": null,
      "investigation_status": "pending",
      "investigation_verdict": "true_positive",
      "investigation_summary": "string",
      "investigation_notebook_short_id": "string",
      "notification_sent_at": "2019-08-24T14:15:22Z",
      "notification_suppressed_by_agent": true,
      "deliveries": [
        {
          "channel": "string",
          "target": "string",
          "target_id": "string",
          "template": "string",
          "status": "string",
          "at": "2019-08-24T14:15:22Z",
          "display_label": "string"
        }
      ]
    }
  ],
  "checks_total": 0,
  "config": {
    "check_ongoing_interval": null,
    "series_index": 0,
    "type": "TrendsAlertConfig"
  },
  "detector_config": {
    "detectors": [
      {
        "preprocessing": null,
        "threshold": null,
        "type": "zscore",
        "window": null
      }
    ],
    "operator": "and",
    "type": "ensemble"
  },
  "calculation_interval": "real_time",
  "snoozed_until": "string",
  "skip_weekend": true,
  "schedule_restriction": {
    "blocked_windows": [
      {
        "start": "string",
        "end": "string"
      }
    ]
  },
  "last_value": 0,
  "investigation_agent_enabled": true,
  "investigation_gates_notifications": true,
  "investigation_inconclusive_action": "notify",
  "search_match_type": "exact"
}

Retrieve alerts

Required API key scopes

alert:read

Path parameters

id
string

Query parameters

checks_date_from
string
checks_date_to
string
checks_limit
integer
checks_offset
integer

Response

Example request

GET /api/projects/:project_id/alerts/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/alerts/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/alerts/{alert_id}/".format(
        project_id=project_id,
		alert_id="<the alert id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "insight": 0,
  "insight_short_id": "string",
  "insight_display_name": "string",
  "name": "string",
  "subscribed_users": [
    0
  ],
  "threshold": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "created_at": "2019-08-24T14:15:22Z",
    "name": "string",
    "configuration": {
      "bounds": null,
      "type": "absolute"
    }
  },
  "condition": {
    "type": "absolute_value"
  },
  "state": "string",
  "enabled": true,
  "last_notified_at": "2019-08-24T14:15:22Z",
  "last_checked_at": "2019-08-24T14:15:22Z",
  "schedule_start_time": "string",
  "next_check_at": "2019-08-24T14:15:22Z",
  "checks": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "created_at": "2019-08-24T14:15:22Z",
      "calculated_value": 0,
      "state": "Firing",
      "error": {
        "property1": "string",
        "property2": "string"
      },
      "targets_notified": true,
      "anomaly_scores": null,
      "triggered_points": null,
      "triggered_dates": null,
      "interval": "string",
      "triggered_metadata": null,
      "investigation_status": "pending",
      "investigation_verdict": "true_positive",
      "investigation_summary": "string",
      "investigation_notebook_short_id": "string",
      "notification_sent_at": "2019-08-24T14:15:22Z",
      "notification_suppressed_by_agent": true,
      "deliveries": [
        {
          "channel": "string",
          "target": "string",
          "target_id": "string",
          "template": "string",
          "status": "string",
          "at": "2019-08-24T14:15:22Z",
          "display_label": "string"
        }
      ]
    }
  ],
  "checks_total": 0,
  "config": {
    "check_ongoing_interval": null,
    "series_index": 0,
    "type": "TrendsAlertConfig"
  },
  "detector_config": {
    "detectors": [
      {
        "preprocessing": null,
        "threshold": null,
        "type": "zscore",
        "window": null
      }
    ],
    "operator": "and",
    "type": "ensemble"
  },
  "calculation_interval": "real_time",
  "snoozed_until": "string",
  "skip_weekend": true,
  "schedule_restriction": {
    "blocked_windows": [
      {
        "start": "string",
        "end": "string"
      }
    ]
  },
  "last_value": 0,
  "investigation_agent_enabled": true,
  "investigation_gates_notifications": true,
  "investigation_inconclusive_action": "notify",
  "search_match_type": "exact"
}

Update alerts

Required API key scopes

alert:write

Path parameters

id
string

Request parameters

insight
integer
name
string
subscribed_users
array
threshold
condition
enabled
boolean
schedule_start_time
stringnull
config
detector_config
calculation_interval
snoozed_until
stringnull
skip_weekend
booleannull
schedule_restriction
investigation_agent_enabled
boolean
investigation_gates_notifications
boolean
investigation_inconclusive_action

Response

Example request

PATCH /api/projects/:project_id/alerts/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/alerts/:id/\
	-d created_by=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/alerts/{alert_id}/".format(
        project_id=project_id,
		alert_id="<the alert id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "insight": 0,
  "insight_short_id": "string",
  "insight_display_name": "string",
  "name": "string",
  "subscribed_users": [
    0
  ],
  "threshold": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "created_at": "2019-08-24T14:15:22Z",
    "name": "string",
    "configuration": {
      "bounds": null,
      "type": "absolute"
    }
  },
  "condition": {
    "type": "absolute_value"
  },
  "state": "string",
  "enabled": true,
  "last_notified_at": "2019-08-24T14:15:22Z",
  "last_checked_at": "2019-08-24T14:15:22Z",
  "schedule_start_time": "string",
  "next_check_at": "2019-08-24T14:15:22Z",
  "checks": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "created_at": "2019-08-24T14:15:22Z",
      "calculated_value": 0,
      "state": "Firing",
      "error": {
        "property1": "string",
        "property2": "string"
      },
      "targets_notified": true,
      "anomaly_scores": null,
      "triggered_points": null,
      "triggered_dates": null,
      "interval": "string",
      "triggered_metadata": null,
      "investigation_status": "pending",
      "investigation_verdict": "true_positive",
      "investigation_summary": "string",
      "investigation_notebook_short_id": "string",
      "notification_sent_at": "2019-08-24T14:15:22Z",
      "notification_suppressed_by_agent": true,
      "deliveries": [
        {
          "channel": "string",
          "target": "string",
          "target_id": "string",
          "template": "string",
          "status": "string",
          "at": "2019-08-24T14:15:22Z",
          "display_label": "string"
        }
      ]
    }
  ],
  "checks_total": 0,
  "config": {
    "check_ongoing_interval": null,
    "series_index": 0,
    "type": "TrendsAlertConfig"
  },
  "detector_config": {
    "detectors": [
      {
        "preprocessing": null,
        "threshold": null,
        "type": "zscore",
        "window": null
      }
    ],
    "operator": "and",
    "type": "ensemble"
  },
  "calculation_interval": "real_time",
  "snoozed_until": "string",
  "skip_weekend": true,
  "schedule_restriction": {
    "blocked_windows": [
      {
        "start": "string",
        "end": "string"
      }
    ]
  },
  "last_value": 0,
  "investigation_agent_enabled": true,
  "investigation_gates_notifications": true,
  "investigation_inconclusive_action": "notify",
  "search_match_type": "exact"
}

Delete alerts

Required API key scopes

alert:write

Path parameters

id
string

Example request

DELETE /api/projects/:project_id/alerts/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/alerts/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/alerts/{alert_id}/".format(
        project_id=project_id,
		alert_id="<the alert id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Create alerts destinations

Send this alert to a Slack channel as well as by email. The workspace must already be connected to the project. The returned IDs identify the destination.

Required API key scopes

alert:write

Path parameters

id
string

Request parameters

type
Default: slack
slack_workspace_id
integer
slack_channel_id
string
slack_channel_name
string

Response

Example request

POST /api/projects/:project_id/alerts/:id/destinations
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/alerts/:id/destinations/\
	-d slack_workspace_id="integer",\
	-d slack_channel_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/alerts/{alert_id}/destinations/".format(
        project_id=project_id,
		alert_id="<the alert id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"slack_workspace_id": "integer",
		"slack_channel_id": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "hog_function_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}

Create alerts destinations delete

Stop sending this alert to a destination. The alert keeps its email recipients.

Required API key scopes

alert:write

Path parameters

id
string

Request parameters

hog_function_ids
array

Example request

POST /api/projects/:project_id/alerts/:id/destinations/delete
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/alerts/:id/destinations/delete/\
	-d hog_function_ids="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/alerts/{alert_id}/destinations/delete/".format(
        project_id=project_id,
		alert_id="<the alert id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"hog_function_ids": "array"
	}
).json()

Example response

Status 204 No response body

Create alerts test delivery

Send a synthetic test notification to subscribed users and every active destination on this alert.

Required API key scopes

alert:write

Path parameters

id
string

Response

Example request

POST /api/projects/:project_id/alerts/:id/test-delivery
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/alerts/:id/test-delivery/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/alerts/{alert_id}/test-delivery/".format(
        project_id=project_id,
		alert_id="<the alert id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 202

RESPONSE
{
  "destination_count": 0,
  "email_recipient_count": 0,
  "failed_delivery_channels": [
    "email"
  ]
}

Create alerts simulate

Simulate a detector on an insight's historical data. Read-only — no AlertCheck records are created.

Required API key scopes

alert:readinsight:read

Request parameters

insight
detector_config
series_index
integer
Default: 0
date_from
stringnull
config

Response

Example request

POST /api/projects/:project_id/alerts/simulate
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/alerts/simulate/\
	-d insight=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/alerts/simulate/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "data": [
    0.1
  ],
  "dates": [
    "string"
  ],
  "scores": [
    0
  ],
  "triggered_indices": [
    0
  ],
  "triggered_dates": [
    "string"
  ],
  "interval": "string",
  "total_points": 0,
  "anomaly_count": 0,
  "sub_detector_scores": [
    {}
  ],
  "breakdown_results": [
    {
      "label": "string",
      "data": [
        0.1
      ],
      "dates": [
        "string"
      ],
      "scores": [
        0
      ],
      "triggered_indices": [
        0
      ],
      "triggered_dates": [
        "string"
      ],
      "total_points": 0,
      "anomaly_count": 0,
      "sub_detector_scores": [
        {}
      ]
    }
  ]
}