Foundational Time Series Model Multi Series Anomaly Detector

curl --request POST \
  --url https://api.nixtla.io/v2/anomaly_detection \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "series": {
    "y": [
      123
    ],
    "sizes": [
      123
    ],
    "X_future": [
      [
        123
      ]
    ],
    "X": [
      [
        123
      ]
    ],
    "categorical_exog": [
      1
    ]
  },
  "freq": "<string>",
  "model": "timegpt-1",
  "clean_ex_first": true,
  "finetuned_model_id": "<string>",
  "multivariate": false,
  "model_parameters": {},
  "hist_exog": [
    1
  ],
  "level": 99,
  "feature_contributions": false
}
'

import requests

url = "https://api.nixtla.io/v2/anomaly_detection"

payload = {
    "series": {
        "y": [123],
        "sizes": [123],
        "X_future": [[123]],
        "X": [[123]],
        "categorical_exog": [1]
    },
    "freq": "<string>",
    "model": "timegpt-1",
    "clean_ex_first": True,
    "finetuned_model_id": "<string>",
    "multivariate": False,
    "model_parameters": {},
    "hist_exog": [1],
    "level": 99,
    "feature_contributions": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    series: {y: [123], sizes: [123], X_future: [[123]], X: [[123]], categorical_exog: [1]},
    freq: '<string>',
    model: 'timegpt-1',
    clean_ex_first: true,
    finetuned_model_id: '<string>',
    multivariate: false,
    model_parameters: {},
    hist_exog: [1],
    level: 99,
    feature_contributions: false
  })
};

fetch('https://api.nixtla.io/v2/anomaly_detection', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nixtla.io/v2/anomaly_detection",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'series' => [
        'y' => [
                123
        ],
        'sizes' => [
                123
        ],
        'X_future' => [
                [
                                123
                ]
        ],
        'X' => [
                [
                                123
                ]
        ],
        'categorical_exog' => [
                1
        ]
    ],
    'freq' => '<string>',
    'model' => 'timegpt-1',
    'clean_ex_first' => true,
    'finetuned_model_id' => '<string>',
    'multivariate' => false,
    'model_parameters' => [
        
    ],
    'hist_exog' => [
        1
    ],
    'level' => 99,
    'feature_contributions' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nixtla.io/v2/anomaly_detection"

	payload := strings.NewReader("{\n  \"series\": {\n    \"y\": [\n      123\n    ],\n    \"sizes\": [\n      123\n    ],\n    \"X_future\": [\n      [\n        123\n      ]\n    ],\n    \"X\": [\n      [\n        123\n      ]\n    ],\n    \"categorical_exog\": [\n      1\n    ]\n  },\n  \"freq\": \"<string>\",\n  \"model\": \"timegpt-1\",\n  \"clean_ex_first\": true,\n  \"finetuned_model_id\": \"<string>\",\n  \"multivariate\": false,\n  \"model_parameters\": {},\n  \"hist_exog\": [\n    1\n  ],\n  \"level\": 99,\n  \"feature_contributions\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.nixtla.io/v2/anomaly_detection")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"series\": {\n    \"y\": [\n      123\n    ],\n    \"sizes\": [\n      123\n    ],\n    \"X_future\": [\n      [\n        123\n      ]\n    ],\n    \"X\": [\n      [\n        123\n      ]\n    ],\n    \"categorical_exog\": [\n      1\n    ]\n  },\n  \"freq\": \"<string>\",\n  \"model\": \"timegpt-1\",\n  \"clean_ex_first\": true,\n  \"finetuned_model_id\": \"<string>\",\n  \"multivariate\": false,\n  \"model_parameters\": {},\n  \"hist_exog\": [\n    1\n  ],\n  \"level\": 99,\n  \"feature_contributions\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nixtla.io/v2/anomaly_detection")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"series\": {\n    \"y\": [\n      123\n    ],\n    \"sizes\": [\n      123\n    ],\n    \"X_future\": [\n      [\n        123\n      ]\n    ],\n    \"X\": [\n      [\n        123\n      ]\n    ],\n    \"categorical_exog\": [\n      1\n    ]\n  },\n  \"freq\": \"<string>\",\n  \"model\": \"timegpt-1\",\n  \"clean_ex_first\": true,\n  \"finetuned_model_id\": \"<string>\",\n  \"multivariate\": false,\n  \"model_parameters\": {},\n  \"hist_exog\": [\n    1\n  ],\n  \"level\": 99,\n  \"feature_contributions\": false\n}"

response = http.request(request)
puts response.read_body

{
  "input_tokens": 1,
  "output_tokens": 1,
  "finetune_tokens": 1,
  "mean": [
    123
  ],
  "sizes": [
    123
  ],
  "anomaly": [
    true
  ],
  "intervals": {},
  "weights_x": [
    123
  ],
  "feature_contributions": [
    [
      123
    ]
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

API Reference

Foundational Time Series Model Multi Series Anomaly Detector

Based on the provided data, this endpoint detects the anomalies in the historical perdiod of multiple time series at once. It takes a JSON as an input containing information like the series frequency and historical data. (See below for a full description of the parameters.) The response contains a flag indicating if the date has an anomaly and also provides the prediction interval used to define if an observation is an anomaly.Get your token at https://www.nixtla.io/book-a-free-trial?utm_source=nixtla.io&utm_campaign=/docs/api-reference.

POST

anomaly_detection

curl --request POST \
  --url https://api.nixtla.io/v2/anomaly_detection \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "series": {
    "y": [
      123
    ],
    "sizes": [
      123
    ],
    "X_future": [
      [
        123
      ]
    ],
    "X": [
      [
        123
      ]
    ],
    "categorical_exog": [
      1
    ]
  },
  "freq": "<string>",
  "model": "timegpt-1",
  "clean_ex_first": true,
  "finetuned_model_id": "<string>",
  "multivariate": false,
  "model_parameters": {},
  "hist_exog": [
    1
  ],
  "level": 99,
  "feature_contributions": false
}
'

import requests

url = "https://api.nixtla.io/v2/anomaly_detection"

payload = {
    "series": {
        "y": [123],
        "sizes": [123],
        "X_future": [[123]],
        "X": [[123]],
        "categorical_exog": [1]
    },
    "freq": "<string>",
    "model": "timegpt-1",
    "clean_ex_first": True,
    "finetuned_model_id": "<string>",
    "multivariate": False,
    "model_parameters": {},
    "hist_exog": [1],
    "level": 99,
    "feature_contributions": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    series: {y: [123], sizes: [123], X_future: [[123]], X: [[123]], categorical_exog: [1]},
    freq: '<string>',
    model: 'timegpt-1',
    clean_ex_first: true,
    finetuned_model_id: '<string>',
    multivariate: false,
    model_parameters: {},
    hist_exog: [1],
    level: 99,
    feature_contributions: false
  })
};

fetch('https://api.nixtla.io/v2/anomaly_detection', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nixtla.io/v2/anomaly_detection",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'series' => [
        'y' => [
                123
        ],
        'sizes' => [
                123
        ],
        'X_future' => [
                [
                                123
                ]
        ],
        'X' => [
                [
                                123
                ]
        ],
        'categorical_exog' => [
                1
        ]
    ],
    'freq' => '<string>',
    'model' => 'timegpt-1',
    'clean_ex_first' => true,
    'finetuned_model_id' => '<string>',
    'multivariate' => false,
    'model_parameters' => [
        
    ],
    'hist_exog' => [
        1
    ],
    'level' => 99,
    'feature_contributions' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nixtla.io/v2/anomaly_detection"

	payload := strings.NewReader("{\n  \"series\": {\n    \"y\": [\n      123\n    ],\n    \"sizes\": [\n      123\n    ],\n    \"X_future\": [\n      [\n        123\n      ]\n    ],\n    \"X\": [\n      [\n        123\n      ]\n    ],\n    \"categorical_exog\": [\n      1\n    ]\n  },\n  \"freq\": \"<string>\",\n  \"model\": \"timegpt-1\",\n  \"clean_ex_first\": true,\n  \"finetuned_model_id\": \"<string>\",\n  \"multivariate\": false,\n  \"model_parameters\": {},\n  \"hist_exog\": [\n    1\n  ],\n  \"level\": 99,\n  \"feature_contributions\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.nixtla.io/v2/anomaly_detection")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"series\": {\n    \"y\": [\n      123\n    ],\n    \"sizes\": [\n      123\n    ],\n    \"X_future\": [\n      [\n        123\n      ]\n    ],\n    \"X\": [\n      [\n        123\n      ]\n    ],\n    \"categorical_exog\": [\n      1\n    ]\n  },\n  \"freq\": \"<string>\",\n  \"model\": \"timegpt-1\",\n  \"clean_ex_first\": true,\n  \"finetuned_model_id\": \"<string>\",\n  \"multivariate\": false,\n  \"model_parameters\": {},\n  \"hist_exog\": [\n    1\n  ],\n  \"level\": 99,\n  \"feature_contributions\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nixtla.io/v2/anomaly_detection")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"series\": {\n    \"y\": [\n      123\n    ],\n    \"sizes\": [\n      123\n    ],\n    \"X_future\": [\n      [\n        123\n      ]\n    ],\n    \"X\": [\n      [\n        123\n      ]\n    ],\n    \"categorical_exog\": [\n      1\n    ]\n  },\n  \"freq\": \"<string>\",\n  \"model\": \"timegpt-1\",\n  \"clean_ex_first\": true,\n  \"finetuned_model_id\": \"<string>\",\n  \"multivariate\": false,\n  \"model_parameters\": {},\n  \"hist_exog\": [\n    1\n  ],\n  \"level\": 99,\n  \"feature_contributions\": false\n}"

response = http.request(request)
puts response.read_body

{
  "input_tokens": 1,
  "output_tokens": 1,
  "finetune_tokens": 1,
  "mean": [
    123
  ],
  "sizes": [
    123
  ],
  "anomaly": [
    true
  ],
  "intervals": {},
  "weights_x": [
    123
  ],
  "feature_contributions": [
    [
      123
    ]
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

HTTPBearer

Body

application/json

series

SeriesWithFutureExogenous · object

required

Show child attributes

freq

string

required

The frequency of the data represented as a string. 'D' for daily, 'M' for monthly, 'H' for hourly, and 'W' for weekly frequencies are available.

model

string

default:timegpt-1

Model to use as a string. Common options are (but not restricted to) timegpt-1 and timegpt-1-long-horizon. Full options vary by different users. Contact support@nixtla.io for more information. We recommend using timegpt-1-long-horizon for forecasting if you want to predict more than one seasonal period given the frequency of your data.

clean_ex_first

boolean

default:true

A boolean flag that indicates whether the API should preprocess (clean) the exogenous signal before applying the large time model. If True, the exogenous signal is cleaned; if False, the exogenous variables are applied after the large time model.

finetuned_model_id

string | null

ID of previously finetuned model

Pattern: ^[a-zA-Z0-9\-_]{1,36}$

multivariate

boolean

default:false

Compute multivariate predictions across a batch of multiple time series. Requires all time series with overlapping dates. Note that this is only effective for timegpt-2.1 model and it has no effect on the other models. By default, the value is set to False.

model_parameters

Model Parameters · object | null

Optional dictionary of parameters to customize the behavior of the large time model.

hist_exog

integer[] | null

Zero-based indices of the exogenous features to treat as historical.

Required range: x >= 0

level

default:99

Specifies the confidence level for the prediction interval used in anomaly detection. It is represented as a percentage between 0 and 100. For instance, a level of 95 indicates that the generated prediction interval captures the true future observation 95% of the time. Any observed values outside of this interval would be considered anomalies. A higher level leads to wider prediction intervals and potentially fewer detected anomalies, whereas a lower level results in narrower intervals and potentially more detected anomalies. Default: 99.

Required range: 0 <= x < 100

feature_contributions

boolean

default:false

Compute the exogenous features contributions to the forecast.

Response

Successful Response

input_tokens

integer

required

Required range: x >= 0

output_tokens

integer

required

Required range: x >= 0

finetune_tokens

integer

required

Required range: x >= 0

mean

number[]

required

sizes

integer[]

required

anomaly

boolean[]

required

intervals

Intervals · object | null

Show child attributes

weights_x

number[] | null

feature_contributions

number[][] | null

Foundational Time Series Model Multi Series Foundational Time Series Model Online Multi Series Anomaly Detector

⌘I

INTRODUCTION

SETUP

DATA REQUIREMENTS

FORECASTING

ANOMALY DETECTION

USE CASES

REFERENCE

About

Foundational Time Series Model Multi Series Anomaly Detector

Authorizations

Body

Response