Overview

The Alerts API lets Scale and Enterprise accounts configure near-real-time DNS traffic alert routes for owned zones or for the whole customer account.

Alert routes define:

The scope to monitor: one zone or the authenticated customer account.
DNS traffic thresholds for QPS, NXDOMAIN ratio, SERVFAIL ratio, and query drops.
Notification channels such as email and webhooks.
Route controls such as status, minimum severity, and cooldown.

Required scopes: alerts:read for read operations and alerts:write for create, update, and delete operations.

Availability

DNS traffic alerts require the dns_traffic_alerts feature entitlement. The feature is enabled by default for Scale and Enterprise plans.

Accounts without this entitlement receive:

{
  "status": "error",
  "error": {
    "code": "FEATURE_NOT_AVAILABLE",
    "message": "DNS traffic alerts are available on Scale and Enterprise plans."
  }
}

Account-level overrides can enable or disable the feature for a specific customer without changing the customer's plan.

Endpoints

Endpoint reference

Method	Endpoint	Description
`GET`	`/v1/alerts`	List alert routes for the authenticated customer
`GET`	`/v1/alerts/{alert_id}`	Get one alert route
`POST`	`/v1/alerts`	Create an alert route
`PATCH`	`/v1/alerts/{alert_id}`	Update an alert route
`DELETE`	`/v1/alerts/{alert_id}`	Delete an alert route

Event Types

Customer-managed routes currently cover zone traffic detectors:

Event type	Description
`ddos_high_qps`	Query volume exceeded the configured QPS threshold
`ddos_nxdomain_spike`	NXDOMAIN response ratio exceeded the configured threshold
`ddos_servfail_spike`	SERVFAIL response ratio exceeded the configured threshold
`ddos_query_drop`	Query volume dropped below the expected baseline

Alert Object

Field	Type	Description
`id`	string	Alert route ID
`customer_id`	string	Authenticated customer ID
`scope_type`	string	`zone` or `account`
`scope_id`	string	Zone UUID or authenticated customer UUID
`thresholds`	number array	Compatibility thresholds; keep `[80, 90]` unless instructed otherwise
`threshold_config`	object	DNS traffic detector thresholds
`status`	string	`enabled` or `disabled`
`severity`	string	Minimum event severity: `info`, `warning`, or `critical`
`cooldown_seconds`	integer	Minimum seconds between notifications for the route
`channels`	array	Notification channels for the route
`created_at`	string	Creation timestamp
`updated_at`	string	Last update timestamp

Threshold Configuration

Field	Description
`qps_warning`	Warning threshold for query volume
`qps_critical`	Critical threshold for query volume
`nxdomain_ratio_warning`	Warning threshold for NXDOMAIN response ratio
`nxdomain_ratio_critical`	Critical threshold for NXDOMAIN response ratio
`servfail_ratio_warning`	Warning threshold for SERVFAIL response ratio
`servfail_ratio_critical`	Critical threshold for SERVFAIL response ratio
`query_drop_threshold`	Query-volume drop threshold compared with baseline
`refused_qps_warning`	Warning threshold for refused-query volume
`refused_qps_critical`	Critical threshold for refused-query volume

On create, omitted threshold_config fields use DNScale defaults. On update, omitted fields keep their existing values.

Channels

Field	Type	Description
`type`	string	`email` or `webhook`
`email_to`	string array	Email recipients for `email` channels
`webhook_url`	string	HTTPS target for `webhook` channels
`enabled`	boolean	Whether this channel can receive notifications

Channel updates replace the complete channel list for the route.

Create A Zone Alert

curl -X POST "https://api.dnscale.eu/v1/alerts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope_type": "zone",
    "scope_id": "zone_uuid_here",
    "thresholds": [80, 90],
    "threshold_config": {
      "qps_warning": 1000,
      "qps_critical": 5000,
      "nxdomain_ratio_warning": 0.3,
      "nxdomain_ratio_critical": 0.5,
      "servfail_ratio_warning": 0.1,
      "servfail_ratio_critical": 0.3
    },
    "status": "enabled",
    "severity": "warning",
    "cooldown_seconds": 900,
    "channels": [
      {
        "type": "email",
        "email_to": ["dns-oncall@example.com"],
        "enabled": true
      }
    ]
  }'

Create An Account Alert

Account alerts apply the same thresholds and channels to all zones owned by the authenticated customer.

curl -X POST "https://api.dnscale.eu/v1/alerts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope_type": "account",
    "scope_id": "customer_uuid_here",
    "thresholds": [80, 90],
    "threshold_config": {
      "qps_warning": 2500,
      "qps_critical": 10000,
      "nxdomain_ratio_warning": 0.25,
      "nxdomain_ratio_critical": 0.5
    },
    "status": "enabled",
    "severity": "warning",
    "cooldown_seconds": 1800,
    "channels": [
      {
        "type": "email",
        "email_to": ["ops@example.com", "dns-oncall@example.com"]
      },
      {
        "type": "webhook",
        "webhook_url": "https://alerts.example.com/dnscale",
        "enabled": false
      }
    ]
  }'

List Alerts

curl "https://api.dnscale.eu/v1/alerts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by zone:

curl "https://api.dnscale.eu/v1/alerts?scope_type=zone&scope_id=zone_uuid_here" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Alerts

Disable a route without deleting it:

curl -X PATCH "https://api.dnscale.eu/v1/alerts/alert_id_here" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "disabled"
  }'

Raise only the NXDOMAIN warning threshold:

curl -X PATCH "https://api.dnscale.eu/v1/alerts/alert_id_here" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "threshold_config": {
      "nxdomain_ratio_warning": 0.4
    }
  }'

Timing

Alerting is near real time, not synchronous with the DNS query path.

Production defaults:

Traffic is evaluated every 60 seconds.
Metrics are aggregated over a 5-minute window.
Duplicate event creation is suppressed for 30 minutes.
Notification delivery usually follows on the next worker poll after an event is created.
cooldown_seconds controls route-level notification pacing after a successful dispatch.

Error Responses

Code	Status	Meaning
`FEATURE_NOT_AVAILABLE`	`403`	The account does not have the DNS traffic alerts entitlement
`FORBIDDEN`	`403`	The requested scope is not owned by the authenticated customer
`INVALID_ALERT`	`400`	The alert route payload is invalid
`ALERT_NOT_FOUND`	`404`	The alert route does not exist or is not visible to the customer