Skip to content
Cloudflare API
Start here
API Reference

Alerting

AlertingAvailable Alerts

Get Alert Types
alerting.available_alerts.list(AvailableAlertListParams**kwargs) -> AvailableAlertListResponse
GET/accounts/{account_id}/alerting/v3/available_alerts
ModelsExpand Collapse
Dict[str, List[AvailableAlertListResponseItem]]
description: Optional[str]

Describes the alert type.

display_name: Optional[str]

Alert type name.

filter_options: Optional[List[object]]

Format of additional configuration options (filters) for the alert type. Data type of filters during policy creation: Array of strings.

type: Optional[str]

Use this value when creating and updating a notification policy.

AlertingDestinations

AlertingDestinationsEligible

Get delivery mechanism eligibility
alerting.destinations.eligible.get(EligibleGetParams**kwargs) -> EligibleGetResponse
GET/accounts/{account_id}/alerting/v3/destinations/eligible
ModelsExpand Collapse
Dict[str, List[EligibleGetResponseItem]]
eligible: Optional[bool]

Determines whether or not the account is eligible for the delivery mechanism.

ready: Optional[bool]

Beta flag. Users can create a policy with a mechanism that is not ready, but we cannot guarantee successful delivery of notifications.

type: Optional[Literal["email", "pagerduty", "webhook"]]

Determines type of delivery mechanism.

One of the following:
"email"
"pagerduty"
"webhook"

AlertingDestinationsPagerduty

List PagerDuty services
alerting.destinations.pagerduty.get(PagerdutyGetParams**kwargs) -> SyncSinglePage[Pagerduty]
GET/accounts/{account_id}/alerting/v3/destinations/pagerduty
Create PagerDuty integration token
alerting.destinations.pagerduty.create(PagerdutyCreateParams**kwargs) -> PagerdutyCreateResponse
POST/accounts/{account_id}/alerting/v3/destinations/pagerduty/connect
Delete PagerDuty Services
alerting.destinations.pagerduty.delete(PagerdutyDeleteParams**kwargs) -> PagerdutyDeleteResponse
DELETE/accounts/{account_id}/alerting/v3/destinations/pagerduty
Connect PagerDuty
alerting.destinations.pagerduty.link(strtoken_id, PagerdutyLinkParams**kwargs) -> PagerdutyLinkResponse
GET/accounts/{account_id}/alerting/v3/destinations/pagerduty/connect/{token_id}
ModelsExpand Collapse
class Pagerduty: …
id: Optional[str]

UUID

maxLength32
name: Optional[str]

The name of the pagerduty service.

class PagerdutyCreateResponse: …
id: Optional[str]

token in form of UUID

maxLength32
class PagerdutyDeleteResponse: …
errors: List[Error]
message: str
code: Optional[int]
minimum1000
messages: List[Message]
message: str
code: Optional[int]
minimum1000
success: Literal[true]

Whether the API call was successful

AlertingDestinationsWebhooks

List webhooks
alerting.destinations.webhooks.list(WebhookListParams**kwargs) -> SyncSinglePage[Webhooks]
GET/accounts/{account_id}/alerting/v3/destinations/webhooks
Get a webhook
alerting.destinations.webhooks.get(strwebhook_id, WebhookGetParams**kwargs) -> Webhooks
GET/accounts/{account_id}/alerting/v3/destinations/webhooks/{webhook_id}
Create a webhook
alerting.destinations.webhooks.create(WebhookCreateParams**kwargs) -> WebhookCreateResponse
POST/accounts/{account_id}/alerting/v3/destinations/webhooks
Update a webhook
alerting.destinations.webhooks.update(strwebhook_id, WebhookUpdateParams**kwargs) -> WebhookUpdateResponse
PUT/accounts/{account_id}/alerting/v3/destinations/webhooks/{webhook_id}
Delete a webhook
alerting.destinations.webhooks.delete(strwebhook_id, WebhookDeleteParams**kwargs) -> WebhookDeleteResponse
DELETE/accounts/{account_id}/alerting/v3/destinations/webhooks/{webhook_id}
ModelsExpand Collapse
class Webhooks: …
id: Optional[str]

The unique identifier of a webhook

maxLength32
created_at: Optional[datetime]

Timestamp of when the webhook destination was created.

formatdate-time
last_failure: Optional[datetime]

Timestamp of the last time an attempt to dispatch a notification to this webhook failed.

formatdate-time
last_success: Optional[datetime]

Timestamp of the last time Cloudflare was able to successfully dispatch a notification using this webhook.

formatdate-time
name: Optional[str]

The name of the webhook destination. This will be included in the request body when you receive a webhook notification.

secret: Optional[str]

Optional secret that will be passed in the cf-webhook-auth header when dispatching generic webhook notifications or formatted for supported destinations. Secrets are not returned in any API response body.

type: Optional[Literal["datadog", "discord", "feishu", 5 more]]

Type of webhook endpoint.

One of the following:
"datadog"
"discord"
"feishu"
"gchat"
"generic"
"opsgenie"
"slack"
"splunk"
url: Optional[str]

The POST endpoint to call when dispatching a notification.

class WebhookCreateResponse: …
id: Optional[str]

UUID

maxLength32
class WebhookUpdateResponse: …
id: Optional[str]

UUID

maxLength32
class WebhookDeleteResponse: …
errors: List[Error]
message: str
code: Optional[int]
minimum1000
messages: List[Message]
message: str
code: Optional[int]
minimum1000
success: Literal[true]

Whether the API call was successful

AlertingHistory

List History
alerting.history.list(HistoryListParams**kwargs) -> SyncV4PagePaginationArray[History]
GET/accounts/{account_id}/alerting/v3/history
ModelsExpand Collapse
class History: …
id: Optional[str]

UUID

maxLength32
alert_body: Optional[str]

Message body included in the notification sent.

alert_type: Optional[str]

Type of notification that has been dispatched.

description: Optional[str]

Description of the notification policy (if present).

mechanism: Optional[str]

The mechanism to which the notification has been dispatched.

mechanism_type: Optional[Literal["email", "pagerduty", "webhook"]]

The type of mechanism to which the notification has been dispatched. This can be email/pagerduty/webhook based on the mechanism configured.

One of the following:
"email"
"pagerduty"
"webhook"
name: Optional[str]

Name of the policy.

policy_id: Optional[str]

The unique identifier of a notification policy

maxLength32
sent: Optional[datetime]

Timestamp of when the notification was dispatched in ISO 8601 format.

formatdate-time

AlertingPolicies

List Notification policies
alerting.policies.list(PolicyListParams**kwargs) -> SyncSinglePage[Policy]
GET/accounts/{account_id}/alerting/v3/policies
Get a Notification policy
alerting.policies.get(strpolicy_id, PolicyGetParams**kwargs) -> Policy
GET/accounts/{account_id}/alerting/v3/policies/{policy_id}
Create a Notification policy
alerting.policies.create(PolicyCreateParams**kwargs) -> PolicyCreateResponse
POST/accounts/{account_id}/alerting/v3/policies
Update a Notification policy
alerting.policies.update(strpolicy_id, PolicyUpdateParams**kwargs) -> PolicyUpdateResponse
PUT/accounts/{account_id}/alerting/v3/policies/{policy_id}
Delete a Notification policy
alerting.policies.delete(strpolicy_id, PolicyDeleteParams**kwargs) -> PolicyDeleteResponse
DELETE/accounts/{account_id}/alerting/v3/policies/{policy_id}
ModelsExpand Collapse
class Mechanism: …

List of IDs that will be used when dispatching a notification. IDs for email type will be the email address.

email: Optional[List[Email]]
id: Optional[str]

The email address

pagerduty: Optional[List[Pagerduty]]
id: Optional[str]

UUID

maxLength32
webhooks: Optional[List[Webhook]]
id: Optional[str]

UUID

maxLength32
class Policy: …
id: Optional[str]

The unique identifier of a notification policy

maxLength32
alert_interval: Optional[str]

Optional specification of how often to re-alert from the same incident, not support on all alert types.

alert_type: Optional[Literal["abuse_report_alert", "access_custom_certificate_expiration_type", "advanced_ddos_attack_l4_alert", 66 more]]

Refers to which event will trigger a Notification dispatch. You can use the endpoint to get available alert types which then will give you a list of possible values.

One of the following:
"abuse_report_alert"
"access_custom_certificate_expiration_type"
"advanced_ddos_attack_l4_alert"
"advanced_ddos_attack_l7_alert"
"advanced_http_alert_error"
"bgp_hijack_notification"
"billing_usage_alert"
"block_notification_block_removed"
"block_notification_new_block"
"block_notification_review_rejected"
"bot_traffic_basic_alert"
"brand_protection_alert"
"brand_protection_digest"
"clickhouse_alert_fw_anomaly"
"clickhouse_alert_fw_ent_anomaly"
"cloudforce_one_request_notification"
"cni_maintenance_notification"
"custom_analytics"
"custom_bot_detection_alert"
"custom_ssl_certificate_event_type"
"dedicated_ssl_certificate_event_type"
"device_connectivity_anomaly_alert"
"dos_attack_l4"
"dos_attack_l7"
"expiring_service_token_alert"
"failing_logpush_job_disabled_alert"
"fbm_auto_advertisement"
"fbm_dosd_attack"
"fbm_volumetric_attack"
"health_check_status_notification"
"hostname_aop_custom_certificate_expiration_type"
"http_alert_edge_error"
"http_alert_origin_error"
"image_notification"
"image_resizing_notification"
"incident_alert"
"load_balancing_health_alert"
"load_balancing_pool_enablement_alert"
"logo_match_alert"
"magic_tunnel_health_check_event"
"magic_wan_tunnel_health"
"maintenance_event_notification"
"mtls_certificate_store_certificate_expiration_type"
"pages_event_alert"
"radar_notification"
"real_origin_monitoring"
"scriptmonitor_alert_new_code_change_detections"
"scriptmonitor_alert_new_hosts"
"scriptmonitor_alert_new_malicious_hosts"
"scriptmonitor_alert_new_malicious_scripts"
"scriptmonitor_alert_new_malicious_url"
"scriptmonitor_alert_new_max_length_resource_url"
"scriptmonitor_alert_new_resources"
"secondary_dns_all_primaries_failing"
"secondary_dns_primaries_failing"
"secondary_dns_warning"
"secondary_dns_zone_successfully_updated"
"secondary_dns_zone_validation_warning"
"security_insights_alert"
"sentinel_alert"
"stream_live_notifications"
"synthetic_test_latency_alert"
"synthetic_test_low_availability_alert"
"traffic_anomalies_alert"
"tunnel_health_event"
"tunnel_update_event"
"universal_ssl_event_type"
"web_analytics_metrics_update"
"zone_aop_custom_certificate_expiration_type"
created: Optional[datetime]
formatdate-time
description: Optional[str]

Optional description for the Notification policy.

enabled: Optional[bool]

Whether or not the Notification policy is enabled.

filters: Optional[PolicyFilter]

Optional filters that allow you to be alerted only on a subset of events for that alert type based on some criteria. This is only available for select alert types. See alert type documentation for more details.

mechanisms: Optional[Mechanism]

List of IDs that will be used when dispatching a notification. IDs for email type will be the email address.

modified: Optional[datetime]
formatdate-time
name: Optional[str]

Name of the policy.

class PolicyFilter: …

Optional filters that allow you to be alerted only on a subset of events for that alert type based on some criteria. This is only available for select alert types. See alert type documentation for more details.

actions: Optional[List[str]]

Usage depends on specific alert type

affected_asns: Optional[List[str]]

Used for configuring radar_notification

affected_components: Optional[List[str]]

Used for configuring incident_alert

affected_locations: Optional[List[str]]

Used for configuring radar_notification

airport_code: Optional[List[str]]

Used for configuring maintenance_event_notification

alert_trigger_preferences: Optional[List[str]]

Usage depends on specific alert type

alert_trigger_preferences_value: Optional[List[str]]

Usage depends on specific alert type

enabled: Optional[List[str]]

Used for configuring load_balancing_pool_enablement_alert

environment: Optional[List[str]]

Used for configuring pages_event_alert

event: Optional[List[str]]

Used for configuring pages_event_alert

event_source: Optional[List[str]]

Used for configuring load_balancing_health_alert

event_type: Optional[List[str]]

Usage depends on specific alert type

group_by: Optional[List[str]]

Usage depends on specific alert type

health_check_id: Optional[List[str]]

Used for configuring health_check_status_notification

incident_impact: Optional[List[Literal["INCIDENT_IMPACT_NONE", "INCIDENT_IMPACT_MINOR", "INCIDENT_IMPACT_MAJOR", "INCIDENT_IMPACT_CRITICAL"]]]

Used for configuring incident_alert

One of the following:
"INCIDENT_IMPACT_NONE"
"INCIDENT_IMPACT_MINOR"
"INCIDENT_IMPACT_MAJOR"
"INCIDENT_IMPACT_CRITICAL"
input_id: Optional[List[str]]

Used for configuring stream_live_notifications

insight_class: Optional[List[str]]

Used for configuring security_insights_alert

limit: Optional[List[str]]

Used for configuring billing_usage_alert

logo_tag: Optional[List[str]]

Used for configuring logo_match_alert

megabits_per_second: Optional[List[str]]

Used for configuring advanced_ddos_attack_l4_alert

new_health: Optional[List[str]]

Used for configuring load_balancing_health_alert

new_status: Optional[List[str]]

Used for configuring tunnel_health_event

packets_per_second: Optional[List[str]]

Used for configuring advanced_ddos_attack_l4_alert

pool_id: Optional[List[str]]

Usage depends on specific alert type

pop_names: Optional[List[str]]

Usage depends on specific alert type

product: Optional[List[str]]

Used for configuring billing_usage_alert

project_id: Optional[List[str]]

Used for configuring pages_event_alert

protocol: Optional[List[str]]

Used for configuring advanced_ddos_attack_l4_alert

query_tag: Optional[List[str]]

Usage depends on specific alert type

requests_per_second: Optional[List[str]]

Used for configuring advanced_ddos_attack_l7_alert

selectors: Optional[List[str]]

Usage depends on specific alert type

services: Optional[List[str]]

Used for configuring clickhouse_alert_fw_ent_anomaly

slo: Optional[List[str]]

Usage depends on specific alert type

status: Optional[List[str]]

Used for configuring health_check_status_notification

target_hostname: Optional[List[str]]

Used for configuring advanced_ddos_attack_l7_alert

target_ip: Optional[List[str]]

Used for configuring advanced_ddos_attack_l4_alert

target_zone_name: Optional[List[str]]

Used for configuring advanced_ddos_attack_l7_alert

traffic_exclusions: Optional[List[Literal["security_events"]]]

Used for configuring traffic_anomalies_alert

tunnel_id: Optional[List[str]]

Used for configuring tunnel_health_event

tunnel_name: Optional[List[str]]

Usage depends on specific alert type

type: Optional[List[str]]

Usage depends on specific alert type

where: Optional[List[str]]

Usage depends on specific alert type

zones: Optional[List[str]]

Usage depends on specific alert type

class PolicyCreateResponse: …
id: Optional[str]

UUID

maxLength32
class PolicyUpdateResponse: …
id: Optional[str]

UUID

maxLength32
class PolicyDeleteResponse: …
errors: List[Error]
message: str
code: Optional[int]
minimum1000
messages: List[Message]
message: str
code: Optional[int]
minimum1000
success: Literal[true]

Whether the API call was successful

result_info: Optional[ResultInfo]
count: Optional[float]

Total number of results for the requested service

page: Optional[float]

Current page within paginated list of results

per_page: Optional[float]

Number of results per page of results

total_count: Optional[float]

Total results available without any search parameters

AlertingSilences

List Silences
alerting.silences.list(SilenceListParams**kwargs) -> SyncSinglePage[SilenceListResponse]
GET/accounts/{account_id}/alerting/v3/silences
Get Silence
alerting.silences.get(strsilence_id, SilenceGetParams**kwargs) -> SilenceGetResponse
GET/accounts/{account_id}/alerting/v3/silences/{silence_id}
Create Silences
alerting.silences.create(SilenceCreateParams**kwargs) -> SilenceCreateResponse
POST/accounts/{account_id}/alerting/v3/silences
Update Silences
alerting.silences.update(SilenceUpdateParams**kwargs) -> SyncSinglePage[SilenceUpdateResponse]
PUT/accounts/{account_id}/alerting/v3/silences
Delete Silence
alerting.silences.delete(strsilence_id, SilenceDeleteParams**kwargs) -> SilenceDeleteResponse
DELETE/accounts/{account_id}/alerting/v3/silences/{silence_id}
ModelsExpand Collapse
class SilenceListResponse: …
id: Optional[str]

Silence ID

maxLength32
created_at: Optional[str]

When the silence was created.

end_time: Optional[str]

When the silence ends.

policy_id: Optional[str]

The unique identifier of a notification policy

maxLength32
start_time: Optional[str]

When the silence starts.

updated_at: Optional[str]

When the silence was modified.

class SilenceGetResponse: …
id: Optional[str]

Silence ID

maxLength32
created_at: Optional[str]

When the silence was created.

end_time: Optional[str]

When the silence ends.

policy_id: Optional[str]

The unique identifier of a notification policy

maxLength32
start_time: Optional[str]

When the silence starts.

updated_at: Optional[str]

When the silence was modified.

class SilenceCreateResponse: …
errors: List[Error]
message: str
code: Optional[int]
minimum1000
messages: List[Message]
message: str
code: Optional[int]
minimum1000
success: Literal[true]

Whether the API call was successful

class SilenceUpdateResponse: …
id: Optional[str]

Silence ID

maxLength32
created_at: Optional[str]

When the silence was created.

end_time: Optional[str]

When the silence ends.

policy_id: Optional[str]

The unique identifier of a notification policy

maxLength32
start_time: Optional[str]

When the silence starts.

updated_at: Optional[str]

When the silence was modified.

class SilenceDeleteResponse: …
errors: List[Error]
message: str
code: Optional[int]
minimum1000
messages: List[Message]
message: str
code: Optional[int]
minimum1000
success: Literal[true]

Whether the API call was successful