nixtla-anomaly-detector

intent-solutions-io's avatarfrom intent-solutions-io

Detects anomalies in time series data using TimeGPT. Identifies outliers, level shifts, and trend breaks without model training. Use when identifying anomalies, outliers, or unusual patterns in time series. Trigger with "detect anomalies", "find outliers", "anomaly detection".

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026
[Reporting]

When & Why to Use This Skill

The Nixtla Anomaly Detector is a high-performance Claude skill designed for automated time series analysis. Leveraging the power of TimeGPT, it identifies outliers, level shifts, and trend breaks in data without the need for complex model training or manual configuration. This tool streamlines the data auditing process by generating comprehensive CSV reports and visual charts, making it an essential asset for professionals looking to maintain data integrity and uncover hidden insights in temporal datasets.

Use Cases

  • E-commerce & Sales: Monitor daily transaction volumes to instantly detect unusual spikes caused by successful promotions or sudden drops due to payment gateway failures.
  • Web Traffic Analysis: Analyze server logs and visitor metrics to identify traffic anomalies that may indicate bot attacks, SEO fluctuations, or technical site issues.
  • Financial Risk Management: Scan historical financial records or stock data to pinpoint trend breaks and outliers that suggest market shifts or potential fraudulent activity.
  • Operational Monitoring: Track IoT sensor data or manufacturing output to flag equipment malfunctions or process deviations before they lead to costly downtime.
namenixtla-anomaly-detector
descriptionDetects anomalies in time series data using TimeGPT. Identifies outliers, level shifts, and trend breaks without model training. Use when identifying anomalies, outliers, or unusual patterns in time series. Trigger with "detect anomalies", "find outliers", "anomaly detection".
allowed-tools"Read,Write,Bash(python:*),Glob,Grep"
version"1.0.0"
author"Jeremy Longshore <jeremy@intentsolutions.io>"
licenseMIT

Nixtla Anomaly Detector

Automatically detect and flag anomalies in time series data using TimeGPT.

Overview

This skill leverages TimeGPT's anomaly detection capabilities to identify outliers, level shifts, and trend breaks in time series data without requiring model training. It accepts CSV data, runs anomaly detection via the Nixtla API, and produces a detailed report with visualizations.

Prerequisites

Required:

  • Python 3.8+
  • nixtla, pandas, matplotlib packages

Environment Variables:

  • NIXTLA_TIMEGPT_API_KEY: Your TimeGPT API key

Installation:

pip install nixtla pandas matplotlib

Instructions

Step 1: Prepare Input Data

Ensure your CSV file has the required Nixtla schema columns:

Column Type Description
unique_id string Series identifier
ds datetime Timestamp
y numeric Value to analyze

Step 2: Set API Key

export NIXTLA_TIMEGPT_API_KEY=your_api_key_here

Step 3: Run Anomaly Detection

Execute the detection script:

python {baseDir}/scripts/detect_anomalies.py --input your_data.csv

Available options:

  • --input, -i: Input CSV file (required)
  • --output-csv, -o: Anomaly output CSV (default: anomalies.csv)
  • --output-plot, -p: Visualization plot (default: anomalies_plot.png)
  • --output-summary, -s: Summary text file (default: anomaly_summary.txt)

Step 4: Review Results

The script generates three output files:

  1. anomalies.csv - Detailed anomaly records
  2. anomalies_plot.png - Visual highlighting of anomalies
  3. anomaly_summary.txt - Summary counts by type

Output

  • anomalies.csv: Contains detected anomalies with timestamps, values, and anomaly types (outlier, level_shift, trend_break)
  • anomalies_plot.png: Time series visualization with anomalies highlighted in red
  • anomaly_summary.txt: Human-readable summary of detection results

Error Handling

  1. Error: NIXTLA_TIMEGPT_API_KEY not set Solution: Run export NIXTLA_TIMEGPT_API_KEY=your_key

  2. Error: CSV file missing required columns Solution: Ensure CSV has unique_id, ds, and y columns

  3. Error: No anomalies detected Solution: This is valid output - data may have no anomalies

  4. Error: Connection error to TimeGPT API Solution: Check network connection and API key validity

Examples

Example 1: Detect outliers in website traffic

Input (traffic.csv):

unique_id,ds,y
website_1,2024-01-01,1000
website_1,2024-01-02,1050
website_1,2024-01-03,300
website_1,2024-01-04,980

Command:

python {baseDir}/scripts/detect_anomalies.py --input traffic.csv

Output (anomalies.csv):

unique_id,ds,y,anomaly_type
website_1,2024-01-03,300,outlier

Example 2: Identify trend break in sales data

Input (sales.csv):

unique_id,ds,y
store_1,2023-12-28,50
store_1,2023-12-29,55
store_1,2023-12-30,60
store_1,2023-12-31,150
store_1,2024-01-01,145

Command:

python {baseDir}/scripts/detect_anomalies.py -i sales.csv -o sales_anomalies.csv

Output: Detects trend break at 2023-12-31

Resources

nixtla-anomaly-detector – AI Agent Skills | Claude Skills