> ## Documentation Index
> Fetch the complete documentation index at: https://moonshotfactory.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Alerts

> Get notified by email or webhook when your agents breach a cost, latency, failure rate, or inactivity threshold.

Alerts notify you when a metric on one of your agents or services crosses a threshold. AgentVista evaluates each active alert on a rolling basis and fires a notification through your chosen delivery channel when the condition is met.

A `cooldown_minutes` setting (default: 60) controls the minimum time between repeated firings of the same alert. This prevents notification floods when a condition persists.

<Note>
  An alert can target either a specific agent (by `agent_id`) or a named service (by `target_service`). You must provide at least one. Latency and cost alerts are commonly targeted at a `target_service` to monitor infrastructure services that are not themselves AI agents.
</Note>

## Alert types

<AccordionGroup>
  <Accordion title="failure_rate — fires when failure rate exceeds a fraction">
    The `failure_rate` alert fires when the fraction of failed runs for the target exceeds the `threshold`.

    The threshold is a decimal fraction from `0.0` to `1.0`. For example, a threshold of `0.20` fires when more than 20% of runs fail.

    <Tip>
      Start with a threshold of `0.10` (10%) for production agents. A threshold that is too tight — such as `0.01` — will fire on normal statistical variation and create alert fatigue.
    </Tip>
  </Accordion>

  <Accordion title="inactivity — fires when an agent has no runs for N hours">
    The `inactivity` alert fires when the target has not received any runs for longer than the `threshold` number of hours.

    For example, a threshold of `24.0` fires if no runs are received for 24 hours. Use this alert to catch silent failures where an agent has stopped running entirely.
  </Accordion>

  <Accordion title="cost_threshold — fires when daily cost exceeds a USD amount">
    The `cost_threshold` alert fires when the target's daily cost exceeds the `threshold` value in USD.

    For example, a threshold of `50.00` fires when daily spend exceeds \$50. Use this alert to catch runaway costs caused by retry loops or unexpectedly high traffic.

    <Tip>
      Set your cost threshold slightly above your expected daily budget, not at the hard limit. This gives you time to respond before spend becomes a problem.
    </Tip>
  </Accordion>

  <Accordion title="latency_threshold — fires when p95 latency exceeds N milliseconds">
    The `latency_threshold` alert fires when the p95 latency for the target exceeds the `threshold` value in milliseconds.

    For example, a threshold of `5000` fires when the 95th percentile of run durations exceeds 5,000 ms (5 seconds).
  </Accordion>

  <Accordion title="composite — custom combination of conditions">
    The `composite` alert type lets you combine AI and infrastructure conditions into a single rule. Use this when you only want to be alerted if multiple conditions are true simultaneously — for example, if your agent's failure rate is high AND your database connection pool is saturated.

    Composite alerts require a `composite_config` object. The `threshold` field is not used for composite alerts.

    **Example `composite_config`:**

    ```json theme={null}
    {
      "operator": "and",
      "conditions": [
        {
          "source": "ai",
          "type": "failure_rate",
          "threshold": 0.20
        },
        {
          "source": "infra",
          "type": "metric_threshold",
          "metric_name": "db.connection_pool.utilization",
          "operator": "gte",
          "value": 0.90
        }
      ]
    }
    ```

    The `operator` field controls how conditions combine: `"and"` fires only when all conditions are met; `"or"` fires when any condition is met. A composite alert must include at least one `"ai"` condition and at least one `"infra"` condition.
  </Accordion>
</AccordionGroup>

## Alert channels

| Channel   | Behavior                                                        |
| --------- | --------------------------------------------------------------- |
| `email`   | Sends a notification to your registered email address (default) |
| `webhook` | Sends an HTTP POST to the `webhook_url` you configure           |
| `both`    | Sends email and webhook simultaneously                          |

When using `webhook` or `both`, you must provide a `webhook_url`.

## Creating an alert

<Tabs>
  <Tab title="UI">
    <Steps>
      <Step title="Open alert settings">
        Go to **Settings → Alerts** and click **Create Alert**.
      </Step>

      <Step title="Choose the alert type">
        Select one of: `failure_rate`, `inactivity`, `cost_threshold`, `latency_threshold`, or `composite`.
      </Step>

      <Step title="Set the target">
        Select an agent from the dropdown, or enter a service name in the **Target service** field for infrastructure alerts.
      </Step>

      <Step title="Set the threshold">
        Enter the threshold value appropriate for the alert type you selected. For composite alerts, configure the `composite_config` JSON instead.
      </Step>

      <Step title="Choose a delivery channel">
        Select `email`, `webhook`, or `both`. If you select `webhook` or `both`, paste your webhook URL.
      </Step>

      <Step title="Save">
        Click **Create**. The alert becomes active immediately.
      </Step>
    </Steps>
  </Tab>

  <Tab title="API">
    Send a `POST` to `/api/v1/alerts` with a JSON body:

    ```json theme={null}
    {
      "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "failure_rate",
      "threshold": 0.20,
      "cooldown_minutes": 60,
      "channel": "webhook",
      "webhook_url": "https://your-service.example.com/hooks/agentvista"
    }
    ```

    For a composite alert targeting a service (not an agent):

    ```json theme={null}
    {
      "target_service": "payments-api",
      "type": "composite",
      "cooldown_minutes": 30,
      "channel": "email",
      "composite_config": {
        "operator": "and",
        "conditions": [
          {
            "source": "ai",
            "type": "failure_rate",
            "threshold": 0.15
          },
          {
            "source": "infra",
            "type": "metric_threshold",
            "metric_name": "http.server.error_rate",
            "operator": "gte",
            "value": 0.05
          }
        ]
      }
    }
    ```

    A successful response returns HTTP 201 with the created alert object.
  </Tab>
</Tabs>

## Managing alerts

You can update an alert's `threshold`, `cooldown_minutes`, `is_active`, `channel`, or `webhook_url` at any time using `PATCH /api/v1/alerts/{alert_id}`. Setting `is_active` to `false` pauses the alert without deleting it.

To permanently remove an alert, send `DELETE /api/v1/alerts/{alert_id}`. Alerts are hard-deleted — this action cannot be undone.