Anomalies - MeshAI Documentation

MeshAI implements four detection algorithms: cost spikes, reliability decay, behavioral drift, and security threats. Detected anomalies are surfaced via the SDK and dashboard.

The expanded anomaly pipeline is live. API PR #84 activated the five-minute production scheduler on August 11, 2026. Three consecutive verified boundaries each elected one runner, completed in 655 ms or less, and reported no errors. The initial 13 continuity incidents were followed by zero duplicate incidents in the next two cycles.

Reliability evidence semantics

Proxy and OTLP sources are evaluated against separate baselines. Error-rate checks require at least 10 baseline requests and 5 recent requests. Latency checks require at least 10 baseline duration samples, 5 recent samples, and 50% duration coverage in both windows. A latency spike is recorded when the recent statistic exceeds three times its baseline. Latency availability comes from valid samples, not from the source label. OTLP spans with missing, malformed, non-positive, or longer-than-24-hour durations remain activity or usage evidence but are excluded from latency. Synthetic spans derived from OTLP logs also do not provide latency. The details.latency_statistic value is mean_of_exact_5m_bucket_p95: each five-minute bucket has an exact p95 across its eligible duration samples, then the detector compares the mean of those bucket values across the baseline and recent windows. It is not an exact percentile across every request in the full window. Sample counts and coverage in details show why latency was or was not eligible. Error-rate detection remains available independently.

list_anomalies()

List anomalies for your tenant, optionally filtered by status, type, or agent.

anomalies = client.list_anomalies(
    status="open",
    anomaly_type="cost_spike",
    agent_id="agt_abc123",
    limit=20,
)

string

Filter by status: open, acknowledged, resolved

string

Filter by type: cost_spike, reliability_decay, behavioral_drift, security_threat

string

Filter by agent ID

integer

default:"20"

Results per page

integer

default:"0"

Results to skip

Returns:

[
  {
    "id": 12345,
    "agent_id": "agt_xyz789",
    "agent_name": "production-summarizer",
    "anomaly_type": "cost_spike",
    "severity": "high",
    "status": "open",
    "description": "Token spend increased 340% vs 7-day average",
    "detected_at": "2026-03-17T09:45:00Z",
    "details": {
      "current_cost_usd": 45.20,
      "baseline_cost_usd": 10.30,
      "deviation_percent": 338.8
    }
  }
]

get_anomaly()

Get a single anomaly by ID.

anomaly = client.get_anomaly(12345)

integer

required

Anomaly event ID

acknowledge_anomaly()

Mark an anomaly as acknowledged. This indicates a human has reviewed it.

client.acknowledge_anomaly(12345)

integer

required

Anomaly event ID

resolve_anomaly()

Mark an anomaly as resolved.

client.resolve_anomaly(12345)

integer

required

Anomaly event ID

get_anomaly_summary()

Get a summary of anomaly counts by type and status.

summary = client.get_anomaly_summary()

Returns:

{
  "total": 12,
  "by_status": {
    "open": 3,
    "acknowledged": 5,
    "resolved": 4
  },
  "by_type": {
    "cost_spike": 6,
    "reliability_decay": 3,
    "behavioral_drift": 2,
    "security_threat": 1
  }
}

​Reliability evidence semantics

​list_anomalies()

​get_anomaly()

​acknowledge_anomaly()

​resolve_anomaly()

​get_anomaly_summary()

Reliability evidence semantics

list_anomalies()

get_anomaly()

acknowledge_anomaly()

resolve_anomaly()

get_anomaly_summary()