TimeGPT accepts pandas and polars dataframes in long format. The minimum required columns are:

Required Columns

  • unique_id: String or numerical value to label each series.
  • ds(timestamp): String or datetime in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format.
  • y(numeric): Numerical target variable to forecast.

Optional Index

If a DataFrame lacks the ds column but uses a DatetimeIndex, that is also supported.
TimeGPT also supports distributed dataframe libraries such as dask, spark, and ray.
Open In Colab
You can include additional exogenous features in the same DataFrame. See the Exogenous Variables tutorial for details.

​
Example DataFrame

Below is a sample of a valid input DataFrame for TimeGPT (with columns named timestamp and value instead of ds and y):
Sample Data Loading
import pandas as pd

df = pd.read_csv('https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv')
df["unique_id"] = "series1"
df.head()

Data Preview

Sample Data Preview
unique_idtimestampvalue
series11949-01-01112
series11949-02-01118
series11949-03-01132
series11949-04-01129
series11949-05-01121
In this example:
  • unique_id identifies the series
  • timestamp corresponds to ds.
  • value corresponds to y.

​
Matching Columns to TimeGPT

You can choose how to align your DataFrame columns with TimeGPT’s expected structure:
Rename timestamp to ds and value to y:
Rename Columns Example
df = df.rename(columns={'timestamp': 'ds', 'value': 'y'})
Now your DataFrame has the explicitly required columns:
Show Head of DataFrame
print(df.head())

​
Example Forecast

When you run the forecast method:
Forecast Example
fcst = nixtla_client.forecast(
    df=df,
    h=12,
    time_col='timestamp',
    target_col='value'
)

fcst.head()
unique_idtimestampTimeGPT
series11961-01-01437.83792
series11961-02-01426.06270
series11961-03-01463.11655
series11961-04-01478.24450
series11961-05-01505.64648

Forecast Output Preview

TimeGPT attempts to automatically infer your data’s frequency (freq). You can override this by specifying the freq parameter (e.g., freq='MS').
For more information, see the TimeGPT Quickstart.

​
Important Considerations

Warning: Data passed to TimeGPT must not contain missing values or time gaps.
To handle missing data, see Dealing with Missing Values in TimeGPT.

​
Minimum Data Requirements (Azure AI)

These are the minimum data sizes required for each frequency when using Azure AI:
FrequencyMinimum Size
Hourly and subhourly (e.g., “H”)1008
Daily (“D”)300
Weekly (e.g., “W-MON”)64
Monthly and others48
When preparing your data, also consider:
1

Forecast horizon (h)

Number of future periods you want to predict.
2

Number of validation windows (n_windows)

How many times to test the model’s performance.
3

Gaps (step_size)

Periodic offset between validation windows during cross-validation.
This ensures you have enough data for both training and evaluation.