Alerts
For instructions on how to authenticate to use this endpoint, see API overview.
Endpoints
GET | |
POST | |
GET | |
PATCH | |
DELETE | |
GET | |
POST | |
POST | |
POST | |
POST | |
POST | |
POST | |
POST | |
POST | |
GET | |
POST |
List all alerts
Also available via the PostHog MCP server:
alerts-list— List alerts
Required API key scopes
alert:readQuery parameters
- created_bystring
- has_detectorboolean
- insight_idinteger
- insight_tagstring
- limitinteger
- offsetinteger
- searchstring
Response
Example request
GET /api /projects /:project_id /alertsExample response
Status 200
Create alerts
Required API key scopes
alert:writeRequest parameters
- insightinteger
- namestring
- subscribed_usersarray
- threshold
- condition
- enabledboolean
- schedule_start_timestring | null
- config
- detector_config
- evaluation_delay_intervalsinteger
- calculation_interval
- snoozed_untilstring | null
- skip_weekendboolean | null
- schedule_restriction
- investigation_agent_enabledboolean
- investigation_gates_notificationsboolean
- investigation_inconclusive_action
Response
Example request
POST /api /projects /:project_id /alertsExample response
Status 201
Retrieve alerts
Required API key scopes
alert:readPath parameters
- idstring
Query parameters
- checks_date_fromstring
- checks_date_tostring
- checks_limitinteger
- checks_offsetinteger
Response
Example request
GET /api /projects /:project_id /alerts /:idExample response
Status 200
Update alerts
Required API key scopes
alert:writePath parameters
- idstring
Request parameters
- insightinteger
- namestring
- subscribed_usersarray
- threshold
- condition
- enabledboolean
- schedule_start_timestring | null
- config
- detector_config
- evaluation_delay_intervalsinteger
- calculation_interval
- snoozed_untilstring | null
- skip_weekendboolean | null
- schedule_restriction
- investigation_agent_enabledboolean
- investigation_gates_notificationsboolean
- investigation_inconclusive_action
Response
Example request
PATCH /api /projects /:project_id /alerts /:idExample response
Status 200
Delete alerts
Required API key scopes
alert:writePath parameters
- idstring
Example request
DELETE /api /projects /:project_id /alerts /:idExample response
Status 204 No response body
List all alerts destinations
This alert's notification destinations, one entry per destination, with credential-bearing URL components removed. Subscribers are listed on the alert instead.
Required API key scopes
alert:readPath parameters
- idstring
Example request
GET /api /projects /:project_id /alerts /:id /destinationsExample response
Status 200
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:writePath parameters
- idstring
Request parameters
- typeDefault:
slack - slack_workspace_idinteger
- slack_channel_idstring
- slack_channel_namestring
Response
Example request
POST /api /projects /:project_id /alerts /:id /destinationsExample response
Status 201
Create alerts destinations customize
Make a destination's message editable. A destination that sends the standard message from the alerts platform gets HogFunctions with that message and stops sending from the platform. A destination that already has HogFunctions keeps them. Returns the HogFunction IDs to edit.
Required API key scopes
alert:writehog_function:writePath parameters
- idstring
Request parameters
- destination_idstring | null
- hog_function_idsarray
Response
Example request
POST /api /projects /:project_id /alerts /:id /destinations /customizeExample response
Status 200
Create alerts destinations delete
Stop sending this alert to a destination. The alert keeps its email recipients.
Required API key scopes
alert:writePath parameters
- idstring
Request parameters
- hog_function_idsarray
- destination_idsarray
Example request
POST /api /projects /:project_id /alerts /:id /destinations /deleteExample response
Status 204 No response body
Create alerts destinations pagerduty
Open a PagerDuty incident when this alert starts firing, and resolve it when the alert stops. Only an alert whose pagerduty_available is true can take one. The returned IDs identify the destination.
Required API key scopes
alert:writehog_function:writePath parameters
- idstring
Request parameters
- pagerduty_routing_keystring
- pagerduty_severityDefault:
critical - pagerduty_regionDefault:
us
Response
Example request
POST /api /projects /:project_id /alerts /:id /destinations /pagerdutyExample response
Status 201
Create alerts destinations reset
Send a customized destination's standard message again. Its HogFunctions are deleted, with their edits, and the alerts platform sends it from then on. Only an alert the alerts platform checks can be reset.
Required API key scopes
alert:writePath parameters
- idstring
Request parameters
- hog_function_idsarray
Response
Example request
POST /api /projects /:project_id /alerts /:id /destinations /resetExample response
Status 200
Create alerts destinations webhook
Send this alert's firings to a Discord or Microsoft Teams channel, or to any webhook. The returned IDs identify the destination.
Required API key scopes
alert:writehog_function:writePath parameters
- idstring
Request parameters
- type
- webhook_urlstring
Response
Example request
POST /api /projects /:project_id /alerts /:id /destinations /webhookExample response
Status 201
Create alerts take ownership
Take ownership of this alert and enable it. Only organization admins can assign another member. The new owner needs access to its content. Checks run with the owner's access, so this is how an alert continues after its owner left.
Required API key scopes
alert:writePath parameters
- idstring
Request parameters
- user_uuidstring
Response
Example request
POST /api /projects /:project_id /alerts /:id /take_ownershipExample response
Status 200
Create alerts test delivery
Send a synthetic test notification to subscribed users and every active destination on this alert.
Required API key scopes
alert:writePath parameters
- idstring
Response
Example request
POST /api /projects /:project_id /alerts /:id /test-deliveryExample response
Status 202
Retrieve alerts pagerduty availability
Whether a new alert with these settings could open PagerDuty incidents once it is created.
Required API key scopes
alert:readQuery parameters
- calculation_intervalstringOne of:
"real_time""every_15_minutes""hourly""daily""weekly""monthly" - investigation_agent_enabledbooleanDefault:
false
Response
Example request
GET /api /projects /:project_id /alerts /pagerduty_availabilityExample response
Status 200
Create alerts simulate
Simulate a detector on an insight's historical data. No AlertCheck records are created. The AI and forecast detectors make real model calls, so those modes need the 'alert:write' scope. The forecast detector scores every point with a one-step forecast from the points before it.
Required API key scopes
alert:readinsight:readRequest parameters
- evaluation_delay_intervalsintegerDefault:
0 - insight
- detector_config
- series_indexintegerDefault:
0 - date_fromstring | null
- config
- alertstring | null
Response
Example request
POST /api /projects /:project_id /alerts /simulate




