> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clustr-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Failed Run Alerts

> Be emailed when a workflow fails, and choose who receives it

Turn failed-run alerts on or off, choose whether each workflow's owner is emailed, and set
extra recipients. When a workflow fails, each recipient gets one email naming the
workflow, how many times it failed, the error, and a link to its runs. An owner hears about
their own workflows; an extra recipient hears about all of them.

<Info>
  **On by default, to the workflow's owner.** The owner is whoever last turned the workflow
  on, else whoever created it. When neither is recorded, or that person is no longer a
  member of the workspace, the email goes to the workspace admins. Addresses are
  de-duplicated across the owner, the admins and the extra recipients.
</Info>

<Info>
  **At most one email a day per unique failure.** A workflow failing the same way every hour is
  mentioned once; a new way of failing is mentioned on the next sweep, within fifteen minutes.
  Import jobs and the built-in scans are not covered yet; they stay on the Runs feed and the
  Needs attention lens the email links to.
</Info>

## Body

<ParamField body="enabled" type="boolean">
  Whether failed-run emails go out at all. Turning it on needs `notify_defaults` or at least
  one recipient.
</ParamField>

<ParamField body="notify_defaults" type="boolean">
  Optional. Whether each failing workflow's owner (or the workspace admins when it has none)
  is emailed. Omit it to keep the saved value, which is `true` until someone changes it.
</ParamField>

<ParamField body="recipients" type="string[]">
  Extra email addresses, on top of the owner. Lower-cased, de-duplicated; an address without
  an `@` is a `400`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT https://api.clustr-ai.com/api/public/notifications/failed-runs \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"enabled": true, "notify_defaults": true, "recipients": ["ops@example.com"]}'
  ```

  ```python Python theme={null}
  import requests

  requests.put(
      "https://api.clustr-ai.com/api/public/notifications/failed-runs",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={"enabled": True, "notify_defaults": True, "recipients": ["ops@example.com"]},
  )
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://api.clustr-ai.com/api/public/notifications/failed-runs", {
    method: "PUT",
    headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
    body: JSON.stringify({ enabled: true, notify_defaults: true, recipients: ["ops@example.com"] }),
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "enabled": true,
      "notify_defaults": true,
      "recipients": ["ops@example.com"],
      "is_default": false,
      "updated_at": "2026-09-18T09:12:44Z"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": {
      "message": "email the workflow's owner or add at least one recipient to turn failed-run alerts on",
      "code": "BAD_REQUEST"
    }
  }
  ```
</ResponseExample>