Foundational Time Series Model Multi Series Cross Validation

curl --request POST \
  --url https://api.nixtla.io/v2/cross_validation \
  --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>",
  "h": 123,
  "n_windows": 1,
  "full_history": false,
  "model": "timegpt-1",
  "clean_ex_first": true,
  "level": [
    50
  ],
  "finetune_steps": 0,
  "finetune_loss": "default",
  "finetune_depth": 1,
  "finetuned_model_id": "<string>",
  "step_size": 1,
  "hist_exog": [
    1
  ],
  "refit": true,
  "multivariate": false,
  "model_parameters": {},
  "feature_contributions": false
}
'

import requests

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

payload = {
    "series": {
        "y": [123],
        "sizes": [123],
        "X_future": [[123]],
        "X": [[123]],
        "categorical_exog": [1]
    },
    "freq": "<string>",
    "h": 123,
    "n_windows": 1,
    "full_history": False,
    "model": "timegpt-1",
    "clean_ex_first": True,
    "level": [50],
    "finetune_steps": 0,
    "finetune_loss": "default",
    "finetune_depth": 1,
    "finetuned_model_id": "<string>",
    "step_size": 1,
    "hist_exog": [1],
    "refit": True,
    "multivariate": False,
    "model_parameters": {},
    "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>',
    h: 123,
    n_windows: 1,
    full_history: false,
    model: 'timegpt-1',
    clean_ex_first: true,
    level: [50],
    finetune_steps: 0,
    finetune_loss: 'default',
    finetune_depth: 1,
    finetuned_model_id: '<string>',
    step_size: 1,
    hist_exog: [1],
    refit: true,
    multivariate: false,
    model_parameters: {},
    feature_contributions: false
  })
};

fetch('https://api.nixtla.io/v2/cross_validation', 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/cross_validation",
  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>',
    'h' => 123,
    'n_windows' => 1,
    'full_history' => false,
    'model' => 'timegpt-1',
    'clean_ex_first' => true,
    'level' => [
        50
    ],
    'finetune_steps' => 0,
    'finetune_loss' => 'default',
    'finetune_depth' => 1,
    'finetuned_model_id' => '<string>',
    'step_size' => 1,
    'hist_exog' => [
        1
    ],
    'refit' => true,
    'multivariate' => false,
    'model_parameters' => [
        
    ],
    '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/cross_validation"

	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  \"h\": 123,\n  \"n_windows\": 1,\n  \"full_history\": false,\n  \"model\": \"timegpt-1\",\n  \"clean_ex_first\": true,\n  \"level\": [\n    50\n  ],\n  \"finetune_steps\": 0,\n  \"finetune_loss\": \"default\",\n  \"finetune_depth\": 1,\n  \"finetuned_model_id\": \"<string>\",\n  \"step_size\": 1,\n  \"hist_exog\": [\n    1\n  ],\n  \"refit\": true,\n  \"multivariate\": false,\n  \"model_parameters\": {},\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/cross_validation")
  .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  \"h\": 123,\n  \"n_windows\": 1,\n  \"full_history\": false,\n  \"model\": \"timegpt-1\",\n  \"clean_ex_first\": true,\n  \"level\": [\n    50\n  ],\n  \"finetune_steps\": 0,\n  \"finetune_loss\": \"default\",\n  \"finetune_depth\": 1,\n  \"finetuned_model_id\": \"<string>\",\n  \"step_size\": 1,\n  \"hist_exog\": [\n    1\n  ],\n  \"refit\": true,\n  \"multivariate\": false,\n  \"model_parameters\": {},\n  \"feature_contributions\": false\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"h\": 123,\n  \"n_windows\": 1,\n  \"full_history\": false,\n  \"model\": \"timegpt-1\",\n  \"clean_ex_first\": true,\n  \"level\": [\n    50\n  ],\n  \"finetune_steps\": 0,\n  \"finetune_loss\": \"default\",\n  \"finetune_depth\": 1,\n  \"finetuned_model_id\": \"<string>\",\n  \"step_size\": 1,\n  \"hist_exog\": [\n    1\n  ],\n  \"refit\": true,\n  \"multivariate\": false,\n  \"model_parameters\": {},\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
  ],
  "idxs": [
    123
  ],
  "intervals": {},
  "feature_contributions": [
    [
      123
    ]
  ]
}

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

POST

cross_validation

Foundational Time Series Model Multi Series Cross Validation

curl --request POST \
  --url https://api.nixtla.io/v2/cross_validation \
  --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>",
  "h": 123,
  "n_windows": 1,
  "full_history": false,
  "model": "timegpt-1",
  "clean_ex_first": true,
  "level": [
    50
  ],
  "finetune_steps": 0,
  "finetune_loss": "default",
  "finetune_depth": 1,
  "finetuned_model_id": "<string>",
  "step_size": 1,
  "hist_exog": [
    1
  ],
  "refit": true,
  "multivariate": false,
  "model_parameters": {},
  "feature_contributions": false
}
'

import requests

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

payload = {
    "series": {
        "y": [123],
        "sizes": [123],
        "X_future": [[123]],
        "X": [[123]],
        "categorical_exog": [1]
    },
    "freq": "<string>",
    "h": 123,
    "n_windows": 1,
    "full_history": False,
    "model": "timegpt-1",
    "clean_ex_first": True,
    "level": [50],
    "finetune_steps": 0,
    "finetune_loss": "default",
    "finetune_depth": 1,
    "finetuned_model_id": "<string>",
    "step_size": 1,
    "hist_exog": [1],
    "refit": True,
    "multivariate": False,
    "model_parameters": {},
    "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>',
    h: 123,
    n_windows: 1,
    full_history: false,
    model: 'timegpt-1',
    clean_ex_first: true,
    level: [50],
    finetune_steps: 0,
    finetune_loss: 'default',
    finetune_depth: 1,
    finetuned_model_id: '<string>',
    step_size: 1,
    hist_exog: [1],
    refit: true,
    multivariate: false,
    model_parameters: {},
    feature_contributions: false
  })
};

fetch('https://api.nixtla.io/v2/cross_validation', 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/cross_validation",
  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>',
    'h' => 123,
    'n_windows' => 1,
    'full_history' => false,
    'model' => 'timegpt-1',
    'clean_ex_first' => true,
    'level' => [
        50
    ],
    'finetune_steps' => 0,
    'finetune_loss' => 'default',
    'finetune_depth' => 1,
    'finetuned_model_id' => '<string>',
    'step_size' => 1,
    'hist_exog' => [
        1
    ],
    'refit' => true,
    'multivariate' => false,
    'model_parameters' => [
        
    ],
    '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/cross_validation"

	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  \"h\": 123,\n  \"n_windows\": 1,\n  \"full_history\": false,\n  \"model\": \"timegpt-1\",\n  \"clean_ex_first\": true,\n  \"level\": [\n    50\n  ],\n  \"finetune_steps\": 0,\n  \"finetune_loss\": \"default\",\n  \"finetune_depth\": 1,\n  \"finetuned_model_id\": \"<string>\",\n  \"step_size\": 1,\n  \"hist_exog\": [\n    1\n  ],\n  \"refit\": true,\n  \"multivariate\": false,\n  \"model_parameters\": {},\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/cross_validation")
  .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  \"h\": 123,\n  \"n_windows\": 1,\n  \"full_history\": false,\n  \"model\": \"timegpt-1\",\n  \"clean_ex_first\": true,\n  \"level\": [\n    50\n  ],\n  \"finetune_steps\": 0,\n  \"finetune_loss\": \"default\",\n  \"finetune_depth\": 1,\n  \"finetuned_model_id\": \"<string>\",\n  \"step_size\": 1,\n  \"hist_exog\": [\n    1\n  ],\n  \"refit\": true,\n  \"multivariate\": false,\n  \"model_parameters\": {},\n  \"feature_contributions\": false\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"h\": 123,\n  \"n_windows\": 1,\n  \"full_history\": false,\n  \"model\": \"timegpt-1\",\n  \"clean_ex_first\": true,\n  \"level\": [\n    50\n  ],\n  \"finetune_steps\": 0,\n  \"finetune_loss\": \"default\",\n  \"finetune_depth\": 1,\n  \"finetuned_model_id\": \"<string>\",\n  \"step_size\": 1,\n  \"hist_exog\": [\n    1\n  ],\n  \"refit\": true,\n  \"multivariate\": false,\n  \"model_parameters\": {},\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
  ],
  "idxs": [
    123
  ],
  "intervals": {},
  "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.

integer

required

The forecasting horizon. This represents the number of time steps into the future that the forecast should predict.

n_windows

integer

default:1

Number of windows to evaluate.

full_history

boolean

default:false

Forecast across the entire series history (the add_history use case). The horizon and number of windows are derived server-side (any supplied h / n_windows are ignored), and the exogenous model is refit a bounded number of times to keep whole-history requests fast. Has no effect without exogenous features.

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.

level

(integer | number)[] | null

A list of values representing the prediction intervals. Each value is a percentage that indicates the level of certainty for the corresponding prediction interval. For example, [80, 90] defines 80% and 90% prediction intervals.

Minimum array length: 1

Required range: 0 <= x < 100

finetune_steps

integer

default:0

The number of tuning steps used to train the large time model on the data. Set this value to 0 for zero-shot inference, i.e., to make predictions without any further model tuning.

Required range: x >= 0

finetune_loss

enum<string>

default:default

The loss used to train the large time model on the data. Select from ['default', 'mae', 'mse', 'rmse', 'mape', 'smape', 'poisson']. It will only be used if finetune_steps larger than 0. Default is a robust loss function that is less sensitive to outliers.

Available options:

default,

mae,

mse,

rmse,

mape,

smape,

poisson

finetune_depth

enum<integer>

default:1

The depth of the finetuning. Uses a scale from 1 to 5, where 1 means little finetuning, and 5 means that the entire model is finetuned. Note that this parameter is only effective for timegpt-1 and timegpt-1-long-horizon models, meanwhile it has no effect on the other models. By default, the value is set to 1.

Available options:

1,

2,

3,

4,

5

finetuned_model_id

string | null

ID of previously finetuned model

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

step_size

integer | null

Step size between each cross validation window. If None it will be equal to the forecasting horizon.

Required range: x > 0

hist_exog

integer[] | null

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

Required range: x >= 0

refit

boolean

default:true

Fine-tune the model in each window. If False, only fine-tunes on the first window. Only used if finetune_steps > 0.

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.

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

idxs

integer[]

required

intervals

Intervals · object | null

Show child attributes

feature_contributions

number[][] | null

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

⌘I

INTRODUCTION

SETUP

DATA REQUIREMENTS

FORECASTING

ANOMALY DETECTION

USE CASES

REFERENCE

About

Foundational Time Series Model Multi Series Cross Validation

Authorizations

Body

Response