Copy page

Forecasting API

Python SDK

For a higher-level interface, use the official Python SDK: theforecastingcompany.

Code
pip install theforecastingcompany

Code
from theforecastingcompany import TFCClient, TFCModels

client = TFCClient()  # reads TFC_API_KEY env var

Simple forecast

Code
import pandas as pd
from theforecastingcompany import TFCClient, TFCModels

client = TFCClient()

train_df = pd.DataFrame({
    "unique_id": ["store_1"] * 100,
    "ds": pd.date_range("2024-01-01", periods=100, freq="D"),
    "target": range(100),
})

forecast_df = client.forecast(
    train_df,
    model=TFCModels.TabPFN_2,
    horizon=14,
    freq="D",
    quantiles=[0.1, 0.5, 0.9],
)

Forecast with exogenous variables

Code
forecast_df = client.forecast(
    train_df,
    future_df=future_df,
    model=TFCModels.TabPFN_2,
    horizon=12,
    freq="W",
    static_variables=["region", "store_type"],
    future_variables=["price", "promotion"],
    add_holidays=True,
    country_isocode="US",
)

Cross-validation (backtesting)

Code
cv_df = client.cross_validate(
    train_df,
    model=TFCModels.TabPFN_2,
    horizon=12,
    freq="W",
    fcds=[pd.Timestamp("2024-06-01"), pd.Timestamp("2024-07-01"), pd.Timestamp("2024-08-01")],
    quantiles=[0.1, 0.5, 0.9],
)

Custom column names

Code
forecast_df = client.forecast(
    my_data,
    model=TFCModels.TimesFM_2p5,
    horizon=7,
    freq="D",
    id_col="item_id",
    date_col="date",
    target_col="sales",
)

Available TFCModels enum values

• TFCModels.TabPFN_2 → "tabpfn-2"
• TFCModels.Moirai_2 → "moirai-2"
• TFCModels.TimesFM_2p5 → "timesfm-2p5"
• TFCModels.Chronos_2 → "chronos-2"
• TFCModels.Tirex → "tirex"
• TFCModels.AutoARIMA → "aarima"
• TFCModels.AutoETS → "aets"

Data structure requirements

DataFrames must have:

• unique_id (or custom id_col): unique identifier for each time series
• ds (or custom date_col): datetime column
• target (or custom target_col): numeric values to forecast

Batch size

Models like chronos-2 and moirai-2 support batching. Control with batch_size (default 256). Increase for speed, decrease if you encounter timeouts.