Skip to main content

​
Anomalies API

Query detected anomalies and manage their status.

​
List Anomalies

GET /api/v1/anomalies

​
Parameters

ParameterTypeDescription
statusstringFilter by status: active, acknowledged, resolved, all
severitystringFilter by severity: info, warning, critical
typestringFilter by type: spike, drop, trend
metricstringFilter by metric name
fromstringStart timestamp (ISO8601)
tostringEnd timestamp (ISO8601)
limitintegerMax results (default: 50)

​
Request

curl "https://flux.brainzlab.ai/api/v1/anomalies?\
status=active&\
severity=critical" \
  -H "Authorization: Bearer sk_live_xxx"

​
Response

{
  "data": [
    {
      "id": "anom_abc123",
      "type": "spike",
      "severity": "critical",
      "status": "active",
      "metric": "api.requests",
      "current_value": 1500,
      "baseline_value": 400,
      "deviation_percent": 275,
      "detected_at": "2024-01-15T14:30:00Z",
      "tags": {
        "endpoint": "/api/users"
      }
    },
    {
      "id": "anom_def456",
      "type": "drop",
      "severity": "warning",
      "status": "active",
      "metric": "orders.count",
      "current_value": 50,
      "baseline_value": 200,
      "deviation_percent": -75,
      "detected_at": "2024-01-15T14:15:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "active": 2,
    "acknowledged": 0
  }
}

​
Get Anomaly

GET /api/v1/anomalies/:id

​
Request

curl "https://flux.brainzlab.ai/api/v1/anomalies/anom_abc123" \
  -H "Authorization: Bearer sk_live_xxx"

​
Response

{
  "data": {
    "id": "anom_abc123",
    "type": "spike",
    "severity": "critical",
    "status": "active",
    "metric": "api.requests",
    "current_value": 1500,
    "baseline_value": 400,
    "deviation_percent": 275,
    "detected_at": "2024-01-15T14:30:00Z",
    "tags": {
      "endpoint": "/api/users"
    },
    "history": [
      { "timestamp": "2024-01-15T14:00:00Z", "value": 420 },
      { "timestamp": "2024-01-15T14:15:00Z", "value": 890 },
      { "timestamp": "2024-01-15T14:30:00Z", "value": 1500 }
    ],
    "baseline_history": [
      { "timestamp": "2024-01-14T14:00:00Z", "value": 380 },
      { "timestamp": "2024-01-14T14:15:00Z", "value": 410 },
      { "timestamp": "2024-01-14T14:30:00Z", "value": 395 }
    ]
  }
}

​
Acknowledge Anomaly

Mark an anomaly as acknowledged: 
POST /api/v1/anomalies/:id/acknowledge

​
Request

curl -X POST https://flux.brainzlab.ai/api/v1/anomalies/anom_abc123/acknowledge \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "Investigating the cause"
  }'

​
Parameters

FieldTypeRequiredDescription
notestringNoOptional note

​
Response

{
  "data": {
    "id": "anom_abc123",
    "status": "acknowledged",
    "acknowledged_at": "2024-01-15T14:45:00Z",
    "acknowledged_by": "user_xyz",
    "note": "Investigating the cause"
  }
}

​
Resolve Anomaly

Mark an anomaly as resolved: 
POST /api/v1/anomalies/:id/resolve

​
Request

curl -X POST https://flux.brainzlab.ai/api/v1/anomalies/anom_abc123/resolve \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "Marketing campaign caused the spike - expected behavior",
    "root_cause": "marketing_campaign"
  }'

​
Parameters

FieldTypeRequiredDescription
notestringNoResolution note
root_causestringNoCategorized root cause

​
Root Cause Categories

ValueDescription
marketing_campaignMarketing activity caused traffic
deploymentRelated to a deployment
external_serviceThird-party service issue
expected_behaviorNormal business pattern
bugApplication bug
infrastructureInfrastructure issue
otherOther cause

​
Response

{
  "data": {
    "id": "anom_abc123",
    "status": "resolved",
    "resolved_at": "2024-01-15T15:00:00Z",
    "resolved_by": "user_xyz",
    "note": "Marketing campaign caused the spike - expected behavior",
    "root_cause": "marketing_campaign"
  }
}

​
Anomaly Stats

Get aggregated anomaly statistics: 
GET /api/v1/anomalies/stats

​
Parameters

ParameterTypeDescription
fromstringStart timestamp
tostringEnd timestamp

​
Request

curl "https://flux.brainzlab.ai/api/v1/anomalies/stats?\
from=2024-01-01&\
to=2024-01-31" \
  -H "Authorization: Bearer sk_live_xxx"

​
Response

{
  "data": {
    "total": 156,
    "by_status": {
      "active": 3,
      "acknowledged": 12,
      "resolved": 141
    },
    "by_severity": {
      "info": 89,
      "warning": 52,
      "critical": 15
    },
    "by_type": {
      "spike": 78,
      "drop": 65,
      "trend": 13
    },
    "by_metric": {
      "api.requests": 45,
      "response_time": 32,
      "orders.count": 28
    },
    "by_root_cause": {
      "marketing_campaign": 23,
      "deployment": 18,
      "expected_behavior": 67,
      "bug": 8
    },
    "mean_time_to_acknowledge": 1800,
    "mean_time_to_resolve": 7200
  }
}

​
Configure Anomaly Detection

Configure detection settings for a metric: 
PUT /api/v1/metrics/:name/anomaly_config

​
Request

curl -X PUT https://flux.brainzlab.ai/api/v1/metrics/api.requests/anomaly_config \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "spike_threshold": 3.0,
    "drop_threshold": 0.3,
    "min_data_points": 100,
    "comparison_window": "7d"
  }'

​
Parameters

FieldTypeDefaultDescription
enabledbooleantrueEnable/disable detection
spike_thresholdnumber3.0Multiplier for spike detection
drop_thresholdnumber0.3Fraction for drop detection
min_data_pointsinteger100Minimum data before detecting
comparison_windowstring7dHistorical window for baseline

​
Response

{
  "data": {
    "metric": "api.requests",
    "enabled": true,
    "spike_threshold": 3.0,
    "drop_threshold": 0.3,
    "min_data_points": 100,
    "comparison_window": "7d"
  }
}

​
Errors

CodeDescription
anomaly_not_foundAnomaly does not exist
already_resolvedAnomaly is already resolved
invalid_thresholdThreshold value is invalid