> ## Documentation Index
> Fetch the complete documentation index at: https://nixtla.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Long-Horizon Forecasting with TimeGPT

> Master long-horizon time series forecasting in Python using TimeGPT. Learn to predict 2+ seasonal periods ahead with confidence intervals and uncertainty quantification.

## What is Long-Horizon Forecasting?

Long-horizon forecasting refers to predictions far into the future, typically exceeding two seasonal periods. For example, forecasting electricity demand 3 months ahead for hourly data, or predicting sales 2 years ahead for monthly data. The exact threshold depends on data frequency. The further you forecast, the more uncertainty you face.

The key challenge with long-horizon forecasting is that these predictions extend so far into the future that they may be influenced by unforeseen factors not present in the initial dataset. This means long-horizon forecasts generally involve greater risk and uncertainty compared to short-term predictions.

To address these unique challenges, Nixtla provides the specialized `timegpt-1-long-horizon` model in TimeGPT. You can access this model by simply specifying `model="timegpt-1-long-horizon"` when calling `nixtla_client.forecast`.

## When to Use Long-Horizon Forecasting

Long-horizon forecasting is ideal for:

* **Supply chain planning**: Predict inventory needs 3-6 months ahead
* **Financial forecasting**: Model quarterly or annual revenue projections
* **Energy demand**: Forecast power consumption weeks or months in advance
* **Climate modeling**: Predict seasonal weather patterns

Use the `timegpt-1-long-horizon` model when your forecast horizon exceeds two complete seasonal cycles in your data.

## How to Use the Long-Horizon Model

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Nixtla/nixtla/blob/main/nbs/docs/tutorials/04_longhorizon.ipynb)

### Step 1: Import Packages

Start by installing and importing the required packages, then initialize the Nixtla client:

```python theme={null}
from nixtla import NixtlaClient
from datasetsforecast.long_horizon import LongHorizon
from utilsforecast.losses import mae

nixtla_client = NixtlaClient(
    api_key='my_api_key_provided_by_nixtla'  # defaults to os.environ.get("NIXTLA_API_KEY")
)
```

### Step 2: Load the Data

We'll demonstrate long-horizon forecasting using the ETTh1 dataset, which measures oil temperatures and load variations on an electricity transformer in China. Here, we only forecast oil temperatures (`y`):

```python theme={null}
Y_df, *_ = LongHorizon.load(directory='./', group='ETTh1')

Y_df.head()
```

|   | unique\_id | ds                  | y        |
| - | ---------- | ------------------- | -------- |
| 0 | OT         | 2016-07-01 00:00:00 | 1.460552 |
| 1 | OT         | 2016-07-01 01:00:00 | 1.161527 |
| 2 | OT         | 2016-07-01 02:00:00 | 1.161527 |
| 3 | OT         | 2016-07-01 03:00:00 | 0.862611 |
| 4 | OT         | 2016-07-01 04:00:00 | 0.525227 |

We'll set our horizon to 96 timestamps (4 days) for testing and use the previous 42 days as input to the model:

```python theme={null}
test = Y_df[-96:]              # 96 timestamps (4 days × 24 hours/day)
input_seq = Y_df[-1104:-96]    # 1008 timestamps (42 days × 24 hours/day)
```

### Step 3: Forecasting with the Long-Horizon Model

TimeGPT's `timegpt-1-long-horizon` model is optimized for predictions far into the future. Specify it like so:

```python theme={null}
fcst_df = nixtla_client.forecast(
    df=input_seq,
    h=96,
    level=[90],
    finetune_steps=10,
    finetune_loss='mae',
    model='timegpt-1-long-horizon',
    time_col='ds',
    target_col='y'
    )
```

Next, plot the forecast along with 90% confidence intervals:

```python theme={null}
nixtla_client.plot(
    Y_df[-168:],
    fcst_df,
    models=['TimeGPT'],
    level=[90],
    time_col='ds',
    target_col='y'
)
```

<Frame caption="TimeGPT Long-Horizon Forecast with 90% Confidence Intervals">
  ![Long-horizon time series forecast showing predicted oil temperature with 90% confidence intervals over 96 hours](https://raw.githubusercontent.com/Nixtla/nixtla/readme_docs/nbs/_docs/docs/tutorials/04_longhorizon_files/figure-markdown_strict/cell-14-output-1.png)
</Frame>

### Step 4: Evaluation

Finally, assess forecast performance using Mean Absolute Error (MAE):

```python theme={null}
test = test.copy()
test.loc[:, 'TimeGPT'] = fcst_df['TimeGPT'].values

evaluation = mae(
    test,
    models=['TimeGPT'],
    id_col='unique_id',
    target_col='y'
)
```

Evaluation result:

| unique\_id | TimeGPT  |
| ---------- | -------- |
| OT         | 0.145393 |

The model achieves a MAE of approximately 0.146, indicating strong performance for these longer-range forecasts.

## Frequently Asked Questions

**Q: What's the difference between timegpt-1 and timegpt-1-long-horizon?**

The `timegpt-1-long-horizon` model is specifically trained for extended forecast horizons (2+ seasonal periods), providing better accuracy for long-range predictions.

**Q: How far ahead can I forecast with the long-horizon model?**

The optimal horizon depends on your data frequency and patterns. Generally, the model performs well up to 4-6 seasonal cycles ahead.

**Q: Can I use exogenous variables with long-horizon forecasting?**

Yes, TimeGPT supports exogenous variables for improved long-horizon accuracy. See our [exogenous variables guide](/forecasting/exogenous-variables/numeric_features) for details.

## Related Resources

Learn more about TimeGPT capabilities:

* [Fine-tuning TimeGPT](/forecasting/fine-tuning/steps) - Improve accuracy for your specific dataset
* [Prediction Intervals](/forecasting/probabilistic/prediction_intervals) - Quantify forecast uncertainty
* [Cross-Validation](/forecasting/evaluation/cross_validation) - Validate model performance
* [Anomaly Detection](/anomaly_detection/historical_anomaly_detection) - Identify unusual patterns in time series