---
title: "Foundational Time Series Model Multi Series Cross Validation"
method: POST
path: "/v2/cross_validation"
---

# Foundational Time Series Model Multi Series Cross Validation

`POST /v2/cross_validation`

Perform Cross Validation for multiple series

## Request body

- CrossValidationInput
  - `series` SeriesWithFutureExogenous, required
    - `X_future` array[], nullable — Future values of the exogenous features. Each feature must be a list of size number of series times the forecast horizon (h).
      - union[]
        - union
          - number
          - string
    - `X` array[], nullable — Historic values of the exogenous features. Each feature must be a list of the same size as the target (y).
      - union[]
        - union
          - number
          - string
    - `categorical_exog` integer[], nullable — Zero-based indices of the columns in X that are categorical features.
    - `y` number[], required — Historic values of the target.
    - `sizes` integer[], required — Sizes of the individual series.
  - `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.
  - `n_windows` integer — Number of windows to evaluate.
  - `h` integer, required — The forecasting horizon. This represents the number of time steps into the future that the forecast should predict.
  - `full_history` boolean — 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 — 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 — 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` union[], nullable — 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.
    - union
      - integer
      - number
  - `finetune_steps` integer — 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.
  - `finetune_loss` 'default' | 'mae' | 'mse' | 'rmse' | 'mape' | 'smape' | 'poisson' — 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.
  - `finetune_depth` 1 | 2 | 3 | 4 | 5 — 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.
  - `finetuned_model_id` string, nullable — ID of previously finetuned model
  - `step_size` integer, nullable — Step size between each cross validation window. If None it will be equal to the forecasting horizon.
  - `hist_exog` integer[], nullable — Zero-based indices of the exogenous features to treat as historical.
  - `refit` boolean — Fine-tune the model in each window. If `False`, only fine-tunes on the first window. Only used if `finetune_steps` > 0.
  - `multivariate` boolean — 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` object, nullable — Optional dictionary of parameters to customize the behavior of the large time model.
  - `feature_contributions` boolean — Compute the exogenous features contributions to the forecast.
  - `feature_contributions_type` 'shapley' | 'intervention' | 'granger' | 'transfer_entropy' — 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.

## Response `200`

Successful Response

- CrossValidationOutput
  - `input_tokens` integer, required
  - `output_tokens` integer, required
  - `finetune_tokens` integer, required
  - `mean` number[], required
  - `sizes` integer[], required
  - `idxs` integer[], required
  - `intervals` object, nullable
  - `feature_contributions` array[], nullable
    - number[]

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/nixtla/apis/nixtla-forecast-api.md) · [All operations](https://skmtc.net/nixtla/apis/nixtla-forecast-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nixtla/nixtla-forecast-api/revisions/f3633293dc24/schema)