# What Is the Maximum Forecast Horizon Supported by TimesFM?

> Discover TimesFM's maximum forecast horizon. Learn how to extend the default 128 time steps for your forecasting needs with Google's TimesFM model. Get the best results.

- Repository: [Google Research/timesfm](https://github.com/google-research/timesfm)
- Tags: faq
- Published: 2026-04-02

---

**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`](https://github.com/google-research/timesfm/blob/main/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.

```python
@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`](https://github.com/google-research/timesfm/blob/main/v1/src/timesfm/timesfm_base.py), the `forecast()` method checks if the requested sequence exceeds the configured limit:

```python
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:

```python
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:

```python
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`](https://github.com/google-research/timesfm/blob/main/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`](https://github.com/google-research/timesfm/blob/main/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.