Skip to main content
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

TypeThreshold meaning
failure_rateFraction 0.0–1.0 — fires when the failure rate exceeds this value (e.g. 0.20 = 20%)
inactivityHours — fires when the agent has not run for this many hours
cost_thresholdUSD — fires when the daily cost exceeds this amount
latency_thresholdMilliseconds — fires when p95 latency exceeds this value
compositeUses composite_config — fires when combined AI + infrastructure conditions are met

​
Delivery channels

ChannelBehavior
emailSends an email to your account address (default)
webhookPosts to your webhook_url
bothSends both email and webhook

​
List alerts

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

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.

​
Response — 201

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

​
Get an alert

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

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 -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.