Alerts

Create and manage alert rules that fire when agent or infrastructure conditions are met.

Alerts let you define threshold-based rules that send notifications when an agent or service crosses a condition. Each alert targets either an agent by UUID or a service by name, and delivers notifications over email, webhook, or both.

---

Alert types

Type	Threshold meaning
failure_rate	Fraction 0.0–1.0 — fires when the failure rate exceeds this value (e.g. 0.20 = 20%)
inactivity	Hours — fires when the agent has not run for this many hours
cost_threshold	USD — fires when the daily cost exceeds this amount
latency_threshold	Milliseconds — fires when p95 latency exceeds this value
composite	Uses composite_config — fires when combined AI + infrastructure conditions are met

Delivery channels

Channel	Behavior
email	Sends an email to your account address (default)
webhook	Posts to your webhook_url
both	Sends both email and webhook

---

List alerts

cURL

curl https://api.agentvista.dev/api/v1/alerts \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

GET /alerts

Returns all alerts associated with agents belonging to the authenticated user.

Response — 200

An array of alert objects.

id · string

Alert UUID.

agent_id · string | null

UUID of the target agent, or null for service-targeted alerts.

agent_name · string | null

Name of the target agent, or null.

type · string

Alert type: failure_rate, inactivity, cost_threshold, latency_threshold, or composite.

threshold · number

Threshold value. Semantics depend on the alert type.

cooldown_minutes · number

Minimum minutes between consecutive firings of this alert.

is_active · boolean

Whether this alert is currently enabled.

channel · string

Delivery channel: email, webhook, or both.

webhook_url · string | null

Webhook delivery URL. Present when channel is webhook or both.

composite_config · object | null

Composite rule definition. Present only for composite type alerts.

target_service · string | null

Service name for service-targeted alerts. Null for agent-targeted alerts.

last_fired_at · string | null

ISO 8601 timestamp of the last time this alert fired.

created_at · string

ISO 8601 timestamp when this alert was created.

---

Create an alert

Failure rate alert

curl -X POST https://api.agentvista.dev/api/v1/alerts \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a",
    "type": "failure_rate",
    "threshold": 0.20,
    "cooldown_minutes": 60,
    "channel": "email"
  }'

POST /alerts

Creates an alert rule. Either agent_id or target_service must be provided. Validation rules:

• failure_rate, inactivity, cost_threshold, and latency_threshold alerts require a threshold value.
• composite alerts require a valid composite_config with at least one ai condition and one infra condition.
• Alerts with channel of webhook or both require a webhook_url.

Request body

agent_id · string

UUID of the agent to monitor. Either agent_id or target_service must be provided.

target_service · string

Service name to monitor (for infrastructure-only alerts). Either agent_id or target_service must be provided.

type · string · required

Alert type: failure_rate, inactivity, cost_threshold, latency_threshold, or composite.

threshold · number · default: "0"

Threshold value. Required for all types except composite. See the alert types table for semantics.

cooldown_minutes · number · default: "60"

Minimum minutes between consecutive firings of this alert.

channel · string · default: "email"

Delivery channel: email, webhook, or both.

webhook_url · string

HTTPS URL to deliver webhook notifications to. Required when channel is webhook or both.

composite_config · object

Composite alert rule. Required when type is composite.

Show composite_config fields

operator · string · required

How to combine conditions: "and" (all must fire) or "or" (any must fire).

conditions · object[] · required

Array of conditions. Must include at least one ai source condition and one infra source condition.

Show condition fields

type · string · required

Condition type: failure_rate, inactivity, cost_threshold, or metric_threshold.

source · string · required

Signal source: "ai" (agent traces) or "infra" (infrastructure metrics).

threshold · number

Threshold value. Used for failure_rate, cost_threshold, and inactivity conditions.

metric_name · string

Metric name to query. Used for metric_threshold conditions.

operator · string

Comparison operator for metric_threshold: "gt", "lt", "gte", or "lte".

value · number

Value to compare against. Used for metric_threshold conditions.

Response — 201

Returns the created alert object. Same schema as the list response.

---

Get an alert

cURL

curl https://api.agentvista.dev/api/v1/alerts/7c3f9a1b-2d5e-4f8a-9b0c-1d2e3f4a5b6c \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

GET /alerts/{alert_id}

Returns a single alert. Returns 404 if the alert does not belong to the authenticated user.

Path parameters

alert_id · string · required

UUID of the alert.

Response — 200

Same schema as a single item from the list response.

---

Update an alert

Pause an alert

curl -X PATCH https://api.agentvista.dev/api/v1/alerts/7c3f9a1b-2d5e-4f8a-9b0c-1d2e3f4a5b6c \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

PATCH /alerts/{alert_id}

Updates one or more mutable fields on an alert. All fields are optional — omit any fields you do not want to change.

Path parameters

alert_id · string · required

UUID of the alert.

Request body

threshold · number

New threshold value.

cooldown_minutes · number

New cooldown period in minutes.

is_active · boolean

Set to false to pause the alert, true to re-enable it.

channel · string

New delivery channel: email, webhook, or both.

webhook_url · string

New webhook URL.

Response — 200

Returns the updated alert object.

---

Delete an alert

cURL

curl -X DELETE https://api.agentvista.dev/api/v1/alerts/7c3f9a1b-2d5e-4f8a-9b0c-1d2e3f4a5b6c \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

DELETE /alerts/{alert_id}

Permanently deletes an alert and all its associated events. This action is irreversible.

Path parameters

alert_id · string · required

UUID of the alert to delete.

Response — 204

No body. The alert has been deleted.