Monitors & Alerts

Overview

Observability: Boards, Logs & Analytics covers how to build dashboards and read logs, and Analytics API: Custom Metric Queries covers pulling that same data programmatically — but both of those are things you have to go look at. This page covers the piece that comes to you: Sulus's monitoring system, which continuously watches your assistants in the background and alerts your team the moment something crosses a threshold you define, without anyone needing to check a dashboard.

The monitoring system has four building blocks that work together:

If you only need to watch spend, Spending Limits & Cost Monitoring already walks through that specific case (a Monitor set to the Infrastructure category with a Cost metric). This page covers the general system underneath it — the other three monitor categories, schedule-based triggers, and the full API path for building a monitor from scratch.

Every monitor is assigned a category, which determines what kind of data it tracks:

Choose the category that matches what you actually want to be told about. A monitor watching for elevated LLM error rates belongs under Technical; one watching call volume against your concurrency plan belongs under Infrastructure; one watching whether callers are getting what they called for belongs under Effectiveness.

A monitor is only useful if something delivers its alerts, so set up your notifier before you build the monitor itself.

1. In the Dashboard, go to Notifiers in the sidebar.
2. Click New Notifier and give it a name.
3. Choose a type: Email (enter a recipient address), Slack (paste a Slack webhook URL), or Webhook (enter your own endpoint URL).
4. Enter the destination and save.

Saving a notifier generates a credential ID. You'll need this ID when you configure a monitor's alert settings — either you select the notifier by name in the Dashboard's monitor builder, or you reference its credential ID directly in the alert.credentialIds array if you're creating the monitor via the API. You can create multiple notifiers and route different monitors to different channels — for example, Technical-category alerts to a Slack channel your engineers watch, and Compliance-category alerts to an email distribution list.

Via the Dashboard

1. Go to Observability > Monitors and click New Monitor.
2. Choose a Category (Technical, Infrastructure, Effectiveness, or Compliance).
3. Set the assistants to target and the escalation thresholds that should trigger an alert.
4. Select the Notifier you already created.
5. Save. The Dashboard automatically creates the underlying analytics query (an Insight) behind the scenes — you don't need to build that separately.

Via the API

Creating a monitor through the API takes one extra step the Dashboard hides from you: you must create the underlying Insight (the analytics query defining what data to evaluate) first, and reference its ID when you create the monitor. The Dashboard flow above creates that Insight automatically when you set your escalation thresholds; the API does not.

Once you have an Insight ID, a full monitor creation request looks like this:

curl -X POST "https://api.sulus.ai/monitoring/monitor" \
  -H "Authorization: Bearer $CORE_SYSTEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "technical",
    "targets": "*",
    "triggers": [
      {
        "insightId": "ins_a1b2c3d4",
        "interval": { "every": 60 },
        "threshold": { "type": "number", "comparator": "gt", "value": 5 },
        "severity": "error",
        "alert": { "credentialIds": ["cred_e5f6g7h8"] }
      }
    ]
  }'

In this example, targets: "*" watches every assistant in the account and automatically includes any assistant created after the monitor is set up. To scope the monitor to specific assistants instead, pass an array of assistant IDs, e.g. "targets": ["asst_123", "asst_456"].

The example above uses an interval-based trigger, which runs every N minutes. If you'd rather evaluate at specific times of day instead of on a fixed interval — for example, only during business hours — use a schedule-based trigger.

Here's a trigger that checks at 9am and 5pm on weekdays only:

{
  "insightId": "ins_a1b2c3d4",
  "schedule": {
    "minute": [0],
    "hour": [9, 17],
    "dayOfWeek": [1, 2, 3, 4, 5]
  },
  "threshold": { "type": "number", "comparator": "gt", "value": 10 },
  "severity": "warning"
}

dayOfWeek uses 0 (Sunday) through 6 (Saturday), so [1, 2, 3, 4, 5] covers Monday through Friday. Use a schedule-based trigger when you want evaluation tied to specific times rather than a fixed cadence; use an interval-based trigger when you want continuous, evenly-spaced checks regardless of time of day.

Once a monitor exists, you can list, update, or remove it through the same endpoint family:

In summary: set up a Notifier first, then build a Monitor around a category and one or more Triggers (interval- or schedule-based), targeting all assistants or a specific set. When a trigger's threshold is crossed, an Issue is created and your Notifier delivers the alert. See Issues & Root Cause Analysis for what happens next, once an Issue has been created.