Skip to main content

​
Overview

Real-time anomaly detection enables you to identify unusual patterns in streaming time series data instantly—essential for monitoring server performance, detecting fraud, identifying system failures, and tracking IoT sensor anomalies. TimeGPT’s detect_anomalies_online method provides:
  • Flexible Control: Fine-tune detection sensitivity and confidence levels
  • Local & Global Detection: Analyze individual series or detect system-wide anomalies across multiple correlated metrics
  • Stream Processing: Monitor live data feeds with rolling window analysis

​
Common Use Cases

  • Server Monitoring: Detect CPU spikes, memory leaks, and downtime
  • IoT Sensors: Identify equipment failures and sensor malfunctions
  • Fraud Detection: Flag suspicious transactions in real-time
  • Application Performance: Monitor API response times and error rates

​
Quick Start

Open In Colab

​
Step 1: Set up your environment

Initialize your Python environment by importing the required libraries: 
import pandas as pd
from nixtla import NixtlaClient
import matplotlib.pyplot as plt

​
Step 2: Configure your NixtlaClient

Provide your API key (and optionally a custom base URL). 
nixtla_client = NixtlaClient(
    # defaults to os.environ.get("NIXTLA_API_KEY")
    api_key='my_api_key_provided_by_nixtla'
)

​
Step 3: Load your dataset

We use a minute-level time series dataset that monitors server usage. This dataset is ideal for showcasing streaming data scenarios, where the task is to detect server failures or downtime in real time. 
df = pd.read_csv(
    'https://datasets-nixtla.s3.us-east-1.amazonaws.com/machine-1-1.csv',
    parse_dates=['ts']
)
We observe that the time series remains stable during the initial period; however, a spike occurs in the last 20 steps, indicating anomalous behavior. Our goal is to capture this abnormal jump as soon as it appears.
Server Data with Spike Anomaly

Server Data with Spike Anomaly

​
Step 4: Detect anomalies in real time

The detect_anomalies_online method detects anomalies in a time series leveraging TimeGPT’s forecast power. It uses the forecast error in deciding the anomalous step so you can specify and tune the parameters like that of the forecast method. This function will return a dataframe that contains anomaly flags and anomaly score (its absolute value quantifies the abnormality of the value). To perform real-time anomaly detection, set the following parameters:
  • df: A pandas DataFrame containing the time series data.
  • time_col: The column that identifies the datestamp.
  • target_col: The variable to forecast.
  • h: Horizon is the number of steps ahead to make a forecast.
  • freq: The frequency of the time series in Pandas format.
  • level: Percentile of scores distribution at which the threshold is set, controlling how strictly anomalies are flagged. Default at 99%.
  • detection_size: The number of steps to analyze for anomaly at the end of time series.
anomaly_online = nixtla_client.detect_anomalies_online(
    df,
    time_col='ts',
    target_col='y',
    freq='min',                # Specify the frequency of the data
    h=10,                      # Specify the forecast horizon
    level=99,                  # Set the confidence level for anomaly detection
    detection_size=100         # Number of steps to analyze for anomalies
)

anomaly_online.tail()
Log Output
INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Calling Online Anomaly Detector Endpoint...
View last 5 anomaly detections:
unique_idtsyTimeGPTanomalyanomaly_scoreTimeGPT-hi-99TimeGPT-lo-99
machine-1-1_y_292020-02-01 22:11:000.6060170.544625True18.4632660.5531610.536090
machine-1-1_y_292020-02-01 22:12:000.0444130.570869True-158.9338500.5794040.562333
machine-1-1_y_292020-02-01 22:13:000.0386820.560303True-157.4748800.5688390.551767
machine-1-1_y_292020-02-01 22:14:000.0243550.521797True-150.1782400.5303330.513261
machine-1-1_y_292020-02-01 22:15:000.0444130.467860True-127.8485600.4763960.459325
Identified Anomalies

Identified Anomalies

From the plot, we observe that the anomalous period is promptly detected.
Here we use a detection size of 100 to illustrate the anomaly detection process. In production, running detections more frequently with smaller detection sizes can help identify anomalies as soon as they occur.

​
Frequently Asked Questions

What’s the difference between online and historical anomaly detection? Online detection analyzes recent data windows for immediate alerting, while historical detection analyzes complete datasets for pattern discovery. Can I adjust detection sensitivity? Yes, tune the level parameter (confidence threshold) and detection_size (analysis window) to control false positive rates.

​
Next Steps

Now that you’ve detected your first anomalies in real-time, explore these guides to optimize your detection: