Foundational Time Series Model Multi Series

Based on the provided data, this endpoint predicts the future values 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 the predicted values for each series based on the input arguments. Get your token at https://nixtla.io/free-trial?utm_source=nixtla.io&utm_campaign=/docs/api-reference.

POST /v2/forecast

Foundational Time Series Model Multi Series

cURL

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

200

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

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.

h · integer · required

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

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 [e-mail] 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}$

feature_contributions · boolean · default: false

Compute the exogenous features contributions to the forecast.

feature_contributions_type · enum<string> · default: shapley

Method used to compute feature contributions. Options are: 'shapley' (default), 'intervention', 'granger', 'transfer_entropy'. The methods differ in semantics: 'shapley' returns per-timestep contributions that sum to the forecast (last row = per-timestep base prediction); 'intervention' returns each feature's counterfactual effect (forecast minus forecast with that feature held at its baseline) and does NOT sum to the forecast; 'granger'/'transfer_entropy' allocate each series' forecast deviation from its mean proportionally to model-agnostic historical importance weights — the rows sum to the forecast by construction, but they are a proportional allocation describing relationships in the data, not a per-feature attribution of this specific forecast. Use the /v2/explain endpoint for standalone historical importance weights.

Available options: shapley, intervention, granger, transfer_entropy

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.

Response

200

application/json

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

intervals · Intervals · object | null

Show child attributes

weights_x · number[] | null

feature_contributions · number[][] | null