What Is the Maximum Forecast Horizon Supported by TimesFM?

TimesFM supports a maximum forecast horizon of 128 time steps by default, defined by the horizon_len hyper-parameter in TimesFmHparams, though this limit can be extended if the model checkpoint was trained with a larger value.

The forecast horizon in the google-research/timesfm repository determines how many future time steps the model predicts in a single inference pass. This capability is controlled by the horizon_len configuration, which enforces strict upper bounds during both model initialization and runtime forecasting to prevent out-of-distribution predictions.

How the Maximum Forecast Horizon Is Defined

In v1/src/timesfm/timesfm_base.py, the TimesFmHparams dataclass establishes the default ceiling for predictions. Lines 68-70 define the horizon_len attribute with a default value of 128, meaning standard checkpoints generate predictions for up to 128 future steps unless explicitly configured otherwise.

@dataclasses.dataclass
class TimesFmHparams:
    # ... other params ...

    horizon_len: int = 128

This value represents the absolute maximum number of autoregressive steps the model architecture will produce for a given time series input.

Runtime Validation of Horizon Requests

During inference, the model validates all request lengths against this hyper-parameter to prevent invalid forecast attempts. At lines 513-518 in v1/src/timesfm/timesfm_base.py, the forecast() method checks if the requested sequence exceeds the configured limit:

if test_lens[-1] > self.horizon_len:
    raise ValueError(
        f"Forecast requested longer horizon than the model definition "
        f"supports: {test_lens[-1]} vs {self.horizon_len}.")

If test_lens[-1]—representing the longest forecast window in the batch—exceeds self.horizon_len, the library immediately raises a ValueError with a descriptive message comparing the requested length against the supported maximum.

Overriding the Default Horizon Limit

While 128 steps is the default constraint, the limit is not architecturally hard-coded. If you possess a checkpoint trained with extended context, you can instantiate TimesFmHparams with a custom horizon_len value that matches the checkpoint's original training configuration. This allows the model to leverage its learned capacity for longer predictive windows.

Practical Implementation Examples

The following example demonstrates standard usage with the default 128-step horizon:

import timesfm

# Use the default horizon (128 steps)

hparams = timesfm.TimesFmHparams()
model = timesfm.TimesFm(hparams, timesfm.TimesFmCheckpoint())
model.load_from_checkpoint(timesfm.TimesFmCheckpoint(path="my_checkpoint"))

# Forecast with the maximum supported horizon

forecast = model.forecast(inputs, freq)   # returns shape (B, N, 128, …)

To utilize a checkpoint trained with a larger horizon, explicitly override the parameter:

import timesfm

# Override the horizon when the checkpoint was trained with a larger one

hparams = timesfm.TimesFmHparams(horizon_len=256)   # custom horizon

model = timesfm.TimesFm(hparams, timesfm.TimesFmCheckpoint(path="large_horizon_ckpt"))
model.load_from_checkpoint(timesfm.TimesFmCheckpoint(path="large_horizon_ckpt"))

# Forecast up to 256 steps (only works if the checkpoint model was trained with that horizon)

forecast = model.forecast(inputs, freq)   # shape (B, N, 256, …)

Summary

• Default maximum: 128 time steps defined in TimesFmHparams within v1/src/timesfm/timesfm_base.py
• Runtime enforcement: Explicit validation at lines 513-518 raises ValueError for excessive horizon requests
• Configurability: The limit can be increased when loading checkpoints trained with larger horizon_len values
• Critical requirement: Always match the horizon_len parameter to your checkpoint's training configuration to avoid runtime errors

Frequently Asked Questions

Can I forecast more than 128 steps with TimesFM?

Yes, but only if your model checkpoint was trained with a larger horizon_len. The default 128-step limit applies to standard checkpoints, but you can override this by setting horizon_len to match your checkpoint's training configuration when constructing TimesFmHparams.

What happens if I request a horizon longer than the model supports?

The library raises a ValueError during the forecast call. As implemented in v1/src/timesfm/timesfm_base.py at lines 513-518, the code explicitly checks test_lens[-1] > self.horizon_len and aborts with a message comparing the requested length against the supported maximum.

How do I verify the maximum horizon for my specific checkpoint?

Check the documentation or training logs for the checkpoint's horizon_len value. When loading a checkpoint, ensure you initialize TimesFmHparams with that specific value; otherwise, the model assumes the default 128 steps and will reject longer forecasts even if the checkpoint weights technically support them.

Does the horizon length affect model performance or accuracy?

The horizon_len determines the prediction window size but does not inherently degrade accuracy if properly matched to the training configuration. However, requesting forecasts beyond what the checkpoint was trained for (without adjusting the hyper-parameter) triggers a hard error rather than reduced accuracy, ensuring you cannot accidentally generate invalid predictions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}