On-Failure Escalation

When a cue execution fails and all retry attempts are exhausted, CueAPI can notify you automatically. The on_failure configuration controls what happens after final failure.

Configuration

The on_failure field accepts three options:

All three options can be combined. By default, email notifications are enabled and the other options are off.

Example: Create a Cue with Escalation

curl -X POST https://api.cueapi.ai/v1/cues \
  -H "Authorization: Bearer cue_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-sync",
    "schedule": {"type": "recurring", "cron": "0 9 * * *"},
    "callback": {"url": "https://api.yourapp.com/sync"},
    "retry": {"max_attempts": 3, "backoff_minutes": [1, 5, 15]},
    "on_failure": {
      "email": true,
      "webhook": "https://api.yourapp.com/alerts/cue-failed",
      "pause": true
    }
  }'

This cue will:

1. Attempt delivery to https://api.yourapp.com/sync
2. Retry up to 3 times with backoff (1min, 5min, 15min)
3. After all retries fail: send you an email, POST to your alert webhook, and pause the cue

Email Notification

When email is true (the default), CueAPI sends a failure alert to the email address associated with your API key. The email includes:

• The cue name and ID
• The execution ID that failed
• The error message (truncated to 500 characters)
• A link to the dashboard

Email notifications are rate limited to 10 per hour per user to prevent inbox flooding.

Webhook Callback

When webhook is set to a URL, CueAPI sends a POST request with the failure details:

{
  "event": "cue.failed",
  "cue_id": "cue_a1b2c3d4e5f6",
  "cue_name": "daily-sync",
  "attempts": 4,
  "last_http_status": 503,
  "last_error": "Service Unavailable",
  "failed_at": "2026-03-16T09:25:00+00:00",
  "dashboard_url": "https://dashboard.cueapi.ai"
}

The webhook URL must pass the same SSRF validation as callback URLs (HTTPS required in production, no private IPs).

Auto-Pause

When pause is true, CueAPI automatically sets the cue status to paused after all retries are exhausted. This prevents the cue from firing again until you manually resume it.

Use this for cues where repeated failures indicate a broken downstream service. You can resume the cue from the dashboard or via PATCH /v1/cues/{id} with {"status": "active"}.

Defaults

If you do not specify on_failure when creating a cue, the defaults apply:

{
  "on_failure": {
    "email": true,
    "webhook": null,
    "pause": false
  }
}

You receive email alerts by default. To disable all escalation:

{
  "on_failure": {
    "email": false
  }
}