5 Min. Lesedauer

GET /anomalies/:websiteId

Retrieve detected anomalies in your analytics data. Returns statistical deviations from expected patterns across key metrics like traffic, bounce rate, conversion rate, and error rate.

GET/api/external/v1/anomalies/:websiteId

Get detected anomalies for a website

Authentication

All requests require an API key passed via the X-API-Key header. Alternatively, you can use the Authorization: Bearer YOUR_API_KEY header.

AuthenticationBash

curl -X GET 'https://api.zenovay.com/api/external/v1/anomalies/a1b2c3d4-e5f6-7890-abcd-ef1234567890?range=7d' \
-H 'X-API-Key: YOUR_API_KEY'

This endpoint requires a Pro plan or higher. Free-tier API keys will receive a 403 Forbidden response.

Credit Cost

Each request to this endpoint costs 1 API credit.

Parameters

Name	Type	Required	Default	Description
`websiteId`	string (path)	Yes	-	The UUID of the website
`range`	string (query)	No	`7d`	Time range: `24h`, `7d`, `30d`, `90d`
`severity`	string (query)	No	-	Filter by severity: `info`, `warning`, `critical`
`metric`	string (query)	No	-	Filter by metric name (e.g. `visitors`, `bounce_rate`, `error_rate`)
`resolved`	string (query)	No	-	Filter by resolution status: `true` or `false`
`limit`	integer (query)	No	`50`	Number of anomalies to return (max: 200)
`offset`	integer (query)	No	`0`	Number of records to skip for pagination

Response

Response (200 OK)JSON

{
"success": true,
"data": {
  "anomalies": [
    {
      "id": "anom_4a5b6c7d-8e9f-0123-abcd-ef4567890123",
      "metric_name": "visitors",
      "expected_value": 850,
      "actual_value": 3240,
      "deviation_percentage": 281.2,
      "severity": "critical",
      "detected_at": "2026-03-16T08:15:00.000Z",
      "is_resolved": false
    },
    {
      "id": "anom_5b6c7d8e-9f01-2345-bcde-f56789012345",
      "metric_name": "bounce_rate",
      "expected_value": 42.5,
      "actual_value": 68.3,
      "deviation_percentage": 60.7,
      "severity": "warning",
      "detected_at": "2026-03-15T22:30:00.000Z",
      "is_resolved": false
    },
    {
      "id": "anom_6c7d8e9f-0123-4567-cdef-678901234567",
      "metric_name": "error_rate",
      "expected_value": 0.8,
      "actual_value": 4.2,
      "deviation_percentage": 425.0,
      "severity": "critical",
      "detected_at": "2026-03-15T16:45:00.000Z",
      "is_resolved": true
    },
    {
      "id": "anom_7d8e9f01-2345-6789-def0-789012345678",
      "metric_name": "page_load_time",
      "expected_value": 1.2,
      "actual_value": 3.8,
      "deviation_percentage": 216.7,
      "severity": "warning",
      "detected_at": "2026-03-15T10:00:00.000Z",
      "is_resolved": true
    }
  ],
  "pagination": {
    "total": 4,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
},
"timestamp": "2026-03-16T15:00:00.000Z"
}

Response Fields

Field	Type	Description
`anomalies`	array	List of detected anomaly records
`anomalies[].id`	string	Unique anomaly identifier
`anomalies[].metric_name`	string	The metric where the anomaly was detected
`anomalies[].expected_value`	number	The expected value based on historical patterns
`anomalies[].actual_value`	number	The actual observed value
`anomalies[].deviation_percentage`	number	Percentage deviation from the expected value
`anomalies[].severity`	string	Severity level: `info`, `warning`, `critical`
`anomalies[].detected_at`	string	ISO 8601 timestamp when the anomaly was detected
`anomalies[].is_resolved`	boolean	Whether the anomaly has returned to normal levels
`pagination.total`	number	Total number of matching anomalies
`pagination.limit`	number	Records per page
`pagination.offset`	number	Current offset
`pagination.has_more`	boolean	Whether more records are available

Severity Levels

Severity	Deviation Threshold	Description
`info`	50-100%	Notable deviation worth monitoring
`warning`	100-200%	Significant deviation requiring attention
`critical`	>200%	Severe deviation requiring immediate action

TypeScript Interface

AnomaliesResponseTypeScript

interface Anomaly {
id: string;
metric_name: string;
expected_value: number;
actual_value: number;
deviation_percentage: number;
severity: 'info' | 'warning' | 'critical';
detected_at: string;
is_resolved: boolean;
}

interface AnomaliesResponse {
success: true;
data: {
  anomalies: Anomaly[];
  pagination: {
    total: number;
    limit: number;
    offset: number;
    has_more: boolean;
  };
};
timestamp: string;
}

HTTP Status Codes

Status Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Pro plan or higher required
404	Not Found - Website not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Code Examples

cURLBash

curl -X GET 'https://api.zenovay.com/api/external/v1/anomalies/a1b2c3d4-e5f6-7890-abcd-ef1234567890?range=7d&severity=critical&resolved=false' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json'

Error Handling

Error Response (403 Forbidden)JSON

{
"success": false,
"error": {
  "message": "This endpoint requires a Pro plan or higher",
  "code": "PLAN_REQUIRED",
  "timestamp": "2026-03-16T15:00:00.000Z"
}
}