Alerts

Alert rules allow you to monitor Mission Control entities (agents, tasks, sessions, activities) and trigger notifications when specific conditions are met. Configure automated alerts for agent failures, stuck tasks, or unusual activity patterns.

List Alert Rules

curl http://localhost:3000/api/alerts \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch('http://localhost:3000/api/alerts', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});
const data = await response.json();

Response

array

Array of alert rule configurations

integer

Alert rule ID

string

Rule name

string

Human-readable description

boolean

Whether rule is active

string

Entity to monitor: agent, task, session, or activity

string

Field to evaluate (e.g., status, priority, assigned_to)

string

Comparison operator: equals, not_equals, greater_than, less_than, contains, count_above, count_below, age_minutes_above

string

Value to compare against

string

Action to take when triggered (default: notification)

object

Configuration for the action (e.g., {"recipient": "admin"})

integer

Minimum time between triggers (default: 60 minutes)

integer

Unix timestamp of last trigger (null if never triggered)

integer

Total number of times this rule has triggered

string

Username who created the rule

integer

Unix timestamp

Create Alert Rule

curl -X POST http://localhost:3000/api/alerts \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "Agent Offline Alert",
    "description": "Alert when agents are offline",
    "entity_type": "agent",
    "condition_field": "status",
    "condition_operator": "equals",
    "condition_value": "offline",
    "action_type": "notification",
    "action_config": {"recipient": "ops-team"},
    "cooldown_minutes": 30
  }'

const response = await fetch('http://localhost:3000/api/alerts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    name: 'Agent Offline Alert',
    entity_type: 'agent',
    condition_field: 'status',
    condition_operator: 'equals',
    condition_value: 'offline',
    cooldown_minutes: 30
  })
});

Request Body

string

required

Rule name for identification

string

Human-readable description of the rule

string

required

Entity to monitor:

agent - Monitor agent status, activity
task - Monitor task status, priority, assignments
session - Monitor gateway sessions
activity - Monitor activity log entries

string

required

Field to evaluate. Allowed fields per entity type:

Agent: status, role, name, last_seen, last_activity
Task: status, priority, assigned_to, title
Activity: type, actor, entity_type

string

required

Comparison operator:

equals - Exact match
not_equals - Not equal
greater_than - Numeric comparison
less_than - Numeric comparison
contains - Substring match (case-insensitive)
count_above - Count of matching entities exceeds value
count_below - Count of matching entities below value
age_minutes_above - Field timestamp older than N minutes

string

required

Value to compare against (stringified)

string

default:"notification"

Action to take when rule triggers

object

Configuration for the action. For notifications: {"recipient": "username"}

integer

default:60

Minimum minutes between rule triggers (prevents spam)

Response

object

Created alert rule object (see List response for schema)

Update Alert Rule

curl -X PUT http://localhost:3000/api/alerts \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "id": 1,
    "enabled": false,
    "cooldown_minutes": 120
  }'

Request Body

integer

required

Alert rule ID to update

string

New rule name

string

New description

boolean

Enable or disable rule

string

Update entity type

string

Update field to monitor

string

Update comparison operator

string

Update comparison value

string

Update action type

object

Update action configuration

integer

Update cooldown period

Delete Alert Rule

curl -X DELETE http://localhost:3000/api/alerts \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"id": 1}'

Request Body

integer

required

Alert rule ID to delete

Evaluate Rules Manually

Trigger immediate evaluation of all enabled alert rules.

curl -X POST http://localhost:3000/api/alerts \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"action": "evaluate"}'

Request Body

string

required

Must be evaluate

Response

integer

Number of rules evaluated

integer

Number of rules that triggered

array

integer

Alert rule ID

string

Rule name

boolean

Whether rule triggered

string

Result reason (e.g., “Condition met”, “In cooldown”)

Rule Examples

Alert on Agent Errors

{
  "name": "Agent Error Alert",
  "entity_type": "agent",
  "condition_field": "status",
  "condition_operator": "equals",
  "condition_value": "error",
  "action_type": "notification",
  "action_config": {"recipient": "ops-team"},
  "cooldown_minutes": 15
}

Alert on High Priority Tasks

{
  "name": "Critical Task Alert",
  "entity_type": "task",
  "condition_field": "priority",
  "condition_operator": "equals",
  "condition_value": "critical",
  "action_type": "notification",
  "cooldown_minutes": 60
}

Alert on Too Many Tasks

{
  "name": "Task Backlog Alert",
  "entity_type": "task",
  "condition_field": "status",
  "condition_operator": "count_above",
  "condition_value": "50",
  "action_type": "notification",
  "cooldown_minutes": 120
}

Alert on Stale Agent Activity

{
  "name": "Stale Agent Alert",
  "entity_type": "agent",
  "condition_field": "last_seen",
  "condition_operator": "age_minutes_above",
  "condition_value": "30",
  "action_type": "notification",
  "cooldown_minutes": 60
}

Alert on Activity Spikes

{
  "name": "High Activity Alert",
  "entity_type": "activity",
  "condition_field": "type",
  "condition_operator": "count_above",
  "condition_value": "100",
  "action_type": "notification",
  "cooldown_minutes": 30
}

The count_above operator for activities checks the count in the last hour only.

Condition Operators

Comparison Operators

Operator	Description	Example
`equals`	Exact match	`status = "error"`
`not_equals`	Not equal	`status != "online"`
`greater_than`	Numeric greater than	`priority > 5`
`less_than`	Numeric less than	`estimated_hours less than 2`
`contains`	Substring (case-insensitive)	`title contains "urgent"`

Aggregate Operators

Operator	Description	Example
`count_above`	Count exceeds value	Count of offline agents > 3
`count_below`	Count below value	Count of in-progress tasks < 5
`age_minutes_above`	Field timestamp older than N minutes	`last_seen` > 30 minutes ago

Cooldown Behavior

Cooldown prevents alert spam:

Rule triggers → creates notification
last_triggered_at timestamp is set
Rule cannot trigger again until cooldown_minutes elapses
During cooldown, evaluation returns "In cooldown"

Example: A rule with cooldown_minutes: 60 can only trigger once per hour, even if the condition remains true.

Notifications

When an alert rule triggers, a notification is created:

{
  "recipient": "ops-team",
  "type": "alert",
  "title": "Alert: Agent Error Alert",
  "message": "Rule 'Agent Error Alert' triggered",
  "source_type": "alert_rule",
  "source_id": 1
}

Notifications appear in:

/api/notifications endpoint
Real-time SSE stream (/api/events)
Mission Control dashboard UI

Automatic Evaluation

Alert rules are evaluated automatically by the scheduler:

Frequency: Every 5 minutes (configurable via MC_ALERT_EVAL_INTERVAL)
Scope: All enabled rules across all workspaces
Cooldown respected: Rules in cooldown are skipped

You can also trigger manual evaluation using POST /api/alerts with {"action": "evaluate"}.

Security Considerations

SQL Injection Protection: Only whitelisted columns are allowed in condition_field
Role Requirements:
- Create/Update: operator role
- Delete: admin role
- List/Evaluate: viewer role
Workspace Isolation: Rules only evaluate entities in their workspace

Best Practices

Use appropriate cooldowns - Balance responsiveness vs. noise
Test with evaluate - Manually trigger evaluation during setup
Monitor trigger counts - High counts may indicate misconfigured rules
Combine with webhooks - Use alerts + webhooks for external integrations
Name descriptively - Use clear names like “Agent Offline > 30min”

Rate Limits

Creation/updates: 100 requests/minute per API key
Evaluation: Manual evaluation limited to 1 request/10 seconds
Automatic evaluation: Every 5 minutes (not user-controlled)

Alert rules that trigger frequently (due to low cooldown or persistent conditions) can generate many notifications. Monitor your notification volume.

Overview

Core Resources

Monitoring

Integrations

Administration

Alerts

Alerts

List Alert Rules

Response

Create Alert Rule

Request Body

Response

Update Alert Rule

Request Body

Delete Alert Rule

Request Body

Evaluate Rules Manually

Request Body

Response

Rule Examples

Alert on Agent Errors

Alert on High Priority Tasks

Alert on Too Many Tasks

Alert on Stale Agent Activity

Alert on Activity Spikes

Condition Operators

Comparison Operators

Aggregate Operators

Cooldown Behavior

Notifications

Automatic Evaluation

Security Considerations

Best Practices

Rate Limits

​Alerts

​List Alert Rules

​Response

​Create Alert Rule

​Request Body

​Response

​Update Alert Rule

​Request Body

​Delete Alert Rule

​Request Body

​Evaluate Rules Manually

​Request Body

​Response

​Rule Examples

​Alert on Agent Errors

​Alert on High Priority Tasks

​Alert on Too Many Tasks

​Alert on Stale Agent Activity

​Alert on Activity Spikes

​Condition Operators

​Comparison Operators

​Aggregate Operators

​Cooldown Behavior

​Notifications

​Automatic Evaluation

​Security Considerations

​Best Practices

​Rate Limits

Alerts

List Alert Rules

Response

Create Alert Rule

Request Body

Response

Update Alert Rule

Request Body

Delete Alert Rule

Request Body

Evaluate Rules Manually

Request Body

Response

Rule Examples

Alert on Agent Errors

Alert on High Priority Tasks

Alert on Too Many Tasks

Alert on Stale Agent Activity

Alert on Activity Spikes

Condition Operators

Comparison Operators

Aggregate Operators

Cooldown Behavior

Notifications

Automatic Evaluation

Security Considerations

Best Practices

Rate Limits