Anomalies API
Find SLOs affected by data anomalies and retrieve continuously detected and Replay anomaly intervals.
Anomalies API
The Anomalies API
The Anomalies API is currently in Beta. Request and response schemas and available endpoints may change.
The Anomalies API is available only with automatic data anomaly detection in Nobl9 Enterprise Edition.
Automatic data anomaly detection must be enabled for your organization. Replay findings require anomaly detection during Replay, and individual anomaly types may have separate rollout schedules. Contact Nobl9 Support if the API or a specific anomaly type is not available.
Authentication and base URL
Authenticate machine-to-machine requests with a Nobl9 access key over HTTP Basic authentication. Use the Client ID as the username and the Client Secret as the password. Bearer access tokens are also supported.
Every endpoint is served under:
https://<your-nobl9-instance>/api/anomalies/v1
Use app.nobl9.com for the EU instance or us1.nobl9.com for the US instance.
Query anomalies
- Call
POST /affected-slosto find SLOs with matching anomalies in a metric-time range. The response groups anomaly counts by status, source, and type. - Pass an SLO from that response to
POST /anomaliesto retrieve its individual anomaly intervals.
Use projects: ["*"] to search all projects you can access. Service filters use project/service; SLO filters use project/slo.
An open anomaly has no affectedTimeRange.to value. The affected range can begin before or end after the requested range when only part of the anomaly overlaps your request. If an SLO does not exist or you cannot access it, POST /anomalies returns an empty items array.
Live and Replay results
By default, the API includes continuously detected anomalies and excludes Replay findings. Set includeReplay to include completed Replay results. This setting does not enable anomaly detection or start Replay analysis.
When live and Replay results are both included:
- A completed Replay result replaces live findings and older Replay results in the metric-time range it covers.
- The newest completed Replay result wins where completed Replay ranges overlap.
- Live findings fill periods not covered by a completed Replay result.
- Incomplete or failed Replay processing does not replace existing results.
- If the newest completed Replay finds no anomaly, no anomaly is returned for its covered range.
Replay anomaly results are eventually consistent and may continue changing after Replay completes. The API returns the current combined result; it does not support selecting a Replay ID or retrieving results from an older Replay.
Filtering and pagination
Both endpoints support filters for anomaly type, resolution status, result source, and time-range matching. The request range must be at least one minute and no more than two years.
With timeRangeMode: "overlap", an anomaly matches when any part remains in the requested range after Replay results are applied. With timeRangeMode: "detected", its original detection time must remain in the requested range.
When using pagination, resend the same filters and explicit from and to values with the returned nextPageToken. Stop when nextPageToken is absent.
Anomaly type names
Use these values in anomalyTypes and when interpreting response categories:
| Data anomaly | API value | Available in Replay |
|---|---|---|
| No data | NoData | No |
| Constant burn | ConstantBurn | Yes |
| No burn | NoBurn | Yes |
| Incremental mismatch | IncrementalViolation | Yes |
| Good over total | GoodOverTotal | Yes, when enabled |
The API values differ from the category values used by the Annotations API.
Authentication
- HTTP: Basic Auth
- HTTP: Bearer Auth
Authenticate with a Nobl9 access key. Use the Client ID as the username and the Client Secret as the password.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | basic |
Authenticate with a Nobl9 access token in the Authorization header.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | JWT |