GETTING STARTED
CAPABILITIES
- Forecast
- State of the art anomaly detection
- Online (Real-Time) Anomaly Detection
DEPLOYMENT
TUTORIALS
- Anomaly detection
- Exogenous variables
- Training
- Fine-tuning
- Validation
- Uncertainty quantification
- Special topics
- Computing at scale
USE CASES
TimeGPT FAQ
Frequently asked questions about TimeGPT
Quick Start
Get started with TimeGPT in minutes
API Reference
Explore the TimeGPT API endpoints
SDK Installation
Set up the Python SDK for TimeGPT
Pricing
Review subscription plans and pricing
Commonly asked questions
TimeGPT is the first foundation model for time series forecasting. It produces accurate forecasts for new time series across diverse domains using only historical values as inputs. The model reads time series data sequentially from left to right, similar to how humans read a sentence. It examines windows of past data as “tokens” and predicts what comes next based on identified patterns that extrapolate into the future. Beyond forecasting, TimeGPT supports other time series tasks, including what-if scenarios and anomaly detection.
TimeGPT is specifically designed for time series data, not text.
No, TimeGPT is not based on any large language model. While it follows the principle of training a large transformer model on a vast dataset, its architecture specifically handles time series data and minimizes forecasting errors.
To get started with TimeGPT, register for an account at dashboard.nixtla.io. After confirming your signup via email, you can access your dashboard with account details.
Sign up
Create an account at dashboard.nixtla.io
Confirm email
Click the confirmation link in your email
Get API key
Find your API key in the dashboard under “API Keys”
Install SDK
Run pip install nixtla to install the Python SDK
For a deeper understanding of TimeGPT, refer to the research paper. While some aspects of the model architecture remain confidential, registration for TimeGPT is open to everyone.
Free Trial Credits
See the Pricing and Billing section for details.
You can use TimeGPT through the Python SDK or the REST API.
from nixtla import NixtlaClient
# Initialize client with your API key
client = NixtlaClient(api_key="your_api_key")
# Make a forecast
forecast = client.forecast(df, h=7)
from nixtla import NixtlaClient
# Initialize client with your API key
client = NixtlaClient(api_key="your_api_key")
# Make a forecast
forecast = client.forecast(df, h=7)
curl -X POST "https://api.nixtla.io/timegpt" \
-H "accept: application/json" \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{"df": [{"ds": "2023-01-01", "y": 100}, ...], "h": 7}'
Both methods require an API key, obtained upon registration and available in your dashboard under “API Keys”.
TimeGPT is the first foundation model for time series forecasting. It produces accurate forecasts for new time series across diverse domains using only historical values as inputs. The model reads time series data sequentially from left to right, similar to how humans read a sentence. It examines windows of past data as “tokens” and predicts what comes next based on identified patterns that extrapolate into the future. Beyond forecasting, TimeGPT supports other time series tasks, including what-if scenarios and anomaly detection.
TimeGPT is specifically designed for time series data, not text.
No, TimeGPT is not based on any large language model. While it follows the principle of training a large transformer model on a vast dataset, its architecture specifically handles time series data and minimizes forecasting errors.
To get started with TimeGPT, register for an account at dashboard.nixtla.io. After confirming your signup via email, you can access your dashboard with account details.
Sign up
Create an account at dashboard.nixtla.io
Confirm email
Click the confirmation link in your email
Get API key
Find your API key in the dashboard under “API Keys”
Install SDK
Run pip install nixtla to install the Python SDK
For a deeper understanding of TimeGPT, refer to the research paper. While some aspects of the model architecture remain confidential, registration for TimeGPT is open to everyone.
Free Trial Credits
See the Pricing and Billing section for details.
You can use TimeGPT through the Python SDK or the REST API.
from nixtla import NixtlaClient
# Initialize client with your API key
client = NixtlaClient(api_key="your_api_key")
# Make a forecast
forecast = client.forecast(df, h=7)
from nixtla import NixtlaClient
# Initialize client with your API key
client = NixtlaClient(api_key="your_api_key")
# Make a forecast
forecast = client.forecast(df, h=7)
curl -X POST "https://api.nixtla.io/timegpt" \
-H "accept: application/json" \
-H "x-api-key: your_api_key" \
-H "Content-Type: application/json" \
-d '{"df": [{"ds": "2023-01-01", "y": 100}, ...], "h": 7}'
Both methods require an API key, obtained upon registration and available in your dashboard under “API Keys”.
An API key is a unique string of characters that authenticates your requests when using the Nixtla SDK, ensuring only authorized users can make requests.
Your API key is personal and should not be shared with anyone or exposed in client-side code.
Upon registration, you receive an API key available in your dashboard under “API Keys”. Keep your API key confidential.
Example API Key location in dashboard
To integrate your API key into your development workflow, refer to the Setting Up Your API Key tutorial.
from nixtla import NixtlaClient
client = NixtlaClient(api_key="your_api_key")
Check your API key status with the validate_api_key method of the NixtlaClient class.
from nixtla import NixtlaClient
nixtla_client = NixtlaClient(api_key='my_api_key_provided_by_nixtla')
nixtla_client.validate_api_key()
INFO:nixtla.nixtla_client:Happy Forecasting! :), If you have questions or need support, please email support@nixtla.io
True
See our Pricing page for information about pricing.
Start for Free
No credit card needed. New users receive $1,000 in free credits.
For customized plan details and offerings, book a demo or contact us at support@nixtla.io.
Sample pricing tiers
Yes! We provide discounted options for academic research. To learn more, email us at support@nixtla.io.
Academic institutions can qualify for special pricing. Contact us for details.
Billing operates through Stripe. We partner with Stripe to handle all payment processing. View your invoices and payment history in your dashboard under “Billing”.
At Nixtla, we take privacy and security very seriously. To ensure you understand our data policies, refer to these documents:
Privacy Notice
Our data privacy policies
License Agreement
Python SDK license
Terms and Conditions
TimeGPT service terms
We are also developing a self-hosted version of TimeGPT for enterprise data with unique security requirements. This version is currently in beta. If interested in this option, contact us at support@nixtla.io.
Common errors and warnings
ApiError: status_code: 401, body: {'data': None, 'message': 'Invalid API key', 'details': 'Key not found', 'code': 'A12', 'requestID': 'E7F2BBTB2P', 'support': 'If you have questions or need support, please email support@nixtla.io'}
This error occurs when your TimeGPT API key is invalid or not set up correctly. Use the validate_api_key method to verify it or check that you copied it correctly from the “API Keys” section of your dashboard.
ApiError: status_code: 429, body: {'data': None, 'message': 'Too many requests', 'details': 'You need to add a payment method to continue using the API, do so from https://dashboard.nixtla.io', 'code': 'A21', 'requestID': 'NCJDK7KSJ6', 'support': 'If you have questions or need support, please email support@nixtla.io'}
This error occurs when you have exhausted your free credits and need to add a payment method to continue using TimeGPT. Add a payment method in the “Billing” section of your dashboard.
A WriteTimeout error indicates the request exceeded allowable processing time. This commonly happens with large datasets. To fix this, increase the num_partitions parameter in the forecast method of the NixtlaClient class, or use a distributed backend.
Get Help with TimeGPT
For more questions or support, reach out through one of our channels:
GitHub Issues
For technical questions or bugs
Email Support
For general inquiries or support
Slack Community
Connect with our team and community
When reporting issues, include your API key status, SDK version, and sample code to help us assist you more quickly.
Features & Capabilities
TimeGPT accepts pandas dataframes in long format with these necessary columns:
You can also pass a DataFrame with a DatetimeIndex without the ds column.
import pandas as pd
# Create sample data
data = {
'ds': ['2023-01-01', '2023-01-02', '2023-01-03'],
'y': [10, 12, 15]
}
df = pd.DataFrame(data)
df['ds'] = pd.to_datetime(df['ds'])
print(df)
TimeGPT also works with distributed dataframes like dask, spark, and ray.
Yes, TimeGPT can forecast multiple time series simultaneously.
For guidance on forecasting multiple time series at once, consult the Multiple Series tutorial.
# Example of forecasting multiple series
from nixtla import NixtlaClient
# Initialize client
client = NixtlaClient(api_key="your_api_key")
# Group identifier for multiple series
df['unique_id'] = df['store_id'] + '_' + df['item_id']
# Forecast multiple series at once
forecast = client.forecast(df, h=7, level=[80, 90])
TimeGPT accepts pandas dataframes in long format with these necessary columns:
You can also pass a DataFrame with a DatetimeIndex without the ds column.
import pandas as pd
# Create sample data
data = {
'ds': ['2023-01-01', '2023-01-02', '2023-01-03'],
'y': [10, 12, 15]
}
df = pd.DataFrame(data)
df['ds'] = pd.to_datetime(df['ds'])
print(df)
TimeGPT also works with distributed dataframes like dask, spark, and ray.
Yes, TimeGPT can forecast multiple time series simultaneously.
For guidance on forecasting multiple time series at once, consult the Multiple Series tutorial.
# Example of forecasting multiple series
from nixtla import NixtlaClient
# Initialize client
client = NixtlaClient(api_key="your_api_key")
# Group identifier for multiple series
df['unique_id'] = df['store_id'] + '_' + df['item_id']
# Forecast multiple series at once
forecast = client.forecast(df, h=7, level=[80, 90])
Yes, TimeGPT can incorporate external variables into forecasts.
For instructions on incorporating exogenous variables to TimeGPT, see the Exogenous Variables tutorial. For incorporating calendar dates, the Holidays and Special Dates tutorial might help. For categorical variables, refer to the Categorical Variables tutorial.
# Forecasting with exogenous variables
forecast = client.forecast(
df,
h=7,
X_df=exog_df # DataFrame with exogenous variables
)
Yes. To forecast historical data using TimeGPT, see the Historical Forecast tutorial.
# Get in-sample predictions
historical_forecast = client.forecast(
df,
h=7,
add_history=True # Include historical predictions
)
Historical vs. Future Forecasting
TimeGPT has no maximum forecast horizon, but performance decreases as the horizon increases. When the forecast horizon exceeds the data’s seasonal length (for example, more than 12 months for monthly data), you will receive this message:
WARNING:nixtla.nixtla_client:The specified horizon "h" exceeds the model horizon. This may lead to less accurate forecasts. Please consider using a smaller horizon
For details, refer to the Long Horizon in Time Series tutorial.
For best results, keep your forecast horizon within the seasonal pattern of your data.
Yes, TimeGPT includes anomaly detection capabilities.
To learn how to use TimeGPT for anomaly detection, refer to the Anomaly Detection tutorial.
# Detect anomalies in time series
anomalies = client.detect_anomalies(df)
Anomaly Detection Example
Yes. To learn how to use TimeGPT for cross-validation, refer to the Cross-Validation tutorial.
# Perform cross-validation
cv_results = client.cross_validation(
df,
h=7,
k=3, # Number of folds
test_size=7 # Size of each test fold
)
Yes. For more information, explore the Prediction Intervals and Quantile Forecasts tutorials.
# Generate prediction intervals
forecast_with_intervals = client.forecast(
df,
h=7,
level=[80, 90, 95] # Confidence levels
)
Forecast with Prediction Intervals
Yes, TimeGPT works with distributed computing frameworks for large datasets.
For large datasets with hundreds of thousands or millions of time series, we recommend using a distributed backend. TimeGPT works with several distributed computing frameworks, including Spark, Ray, and Dask.
import dask.dataframe as dd
# Convert to Dask DataFrame
dask_df = dd.from_pandas(df, npartitions=4)
# Forecast using Dask backend
forecast = client.forecast(dask_df, h=7)
TimeGPT supports any amount of data for generating point forecasts and can produce results with just one observation per series. When using arguments such as level, finetune_steps, X_df (exogenous variables), or add_history, additional data points are necessary depending on data frequency. For more details, refer to the Data Requirements tutorial.
While TimeGPT can work with minimal data, more historical data typically produces better forecasts.
TimeGPT cannot handle missing values or series with irregular timestamps.
For more information, see the Forecasting Time Series with Irregular Timestamps and Dealing with Missing Values tutorials.
The NixtlaClient class has a plot method for visualizing forecasts. This method works only in interactive environments such as Jupyter notebooks, not in Python scripts.
# Plot forecast
client.plot(
historical_data=df,
forecast_data=forecast,
level=[80, 95] # Optional: show prediction intervals
)
Sample TimeGPT Forecast Visualization
Currently, TimeGPT does not support polars.
Yes, TimeGPT produces consistent results for identical inputs.
TimeGPT is engineered for stability, ensuring consistent results for identical input data. Given the same dataset, the model will produce the same forecasts.
While not the primary use case for TimeGPT, it can generate solid results on simple data patterns like straight lines. Zero-shot predictions might not always meet expectations, but fine-tuning allows TimeGPT to quickly grasp trends and produce accurate forecasts. For more details, refer to the Improve Forecast Accuracy with TimeGPT tutorial.
Fine-tuning improves TimeGPT’s performance for your specific data patterns.
TimeGPT was trained on the largest publicly available time series dataset, covering domains including finance, retail, healthcare, and more. This comprehensive training enables TimeGPT to produce accurate forecasts for new time series without additional training (zero-shot learning).
While the zero-shot model provides a solid baseline, TimeGPT performance often improves through fine-tuning. During this process, the TimeGPT model undergoes additional training using your specific dataset, starting from the pre-trained parameters.
Fine-tuning Concept
# Fine-tune with 100 steps
forecast = client.forecast(
df,
h=7,
finetune_steps=100,
finetune_loss="mse" # Mean Squared Error
)
For a comprehensive guide on fine-tuning, refer to the fine-tuning and fine-tuning with a specific loss function tutorials.
No, you do not need to fine-tune every series individually. When using the finetune_steps parameter, the model fine-tunes across all series in your dataset simultaneously. This cross-learning approach allows the model to learn from multiple series at once, which can improve individual forecasts.
Selecting the right number of fine-tuning steps may require experimentation. As fine-tuning steps increase, the model becomes more specialized to your dataset but takes longer to train and may become more prone to overfitting.
Yes, you can save and reuse fine-tuned models.
You can fine-tune the TimeGPT model, save it, and reuse it later. For detailed instructions, see our guide on Re-using Fine-tuned Models.
# Fine-tune and save the model
fine_tuned_parameters = client.forecast(
df,
h=7,
finetune_steps=100,
return_model=True # Return the fine-tuned parameters
)
# Save to file
import pickle
with open("fine_tuned_model.pkl", "wb") as f:
pickle.dump(fine_tuned_parameters, f)
# Fine-tune and save the model
fine_tuned_parameters = client.forecast(
df,
h=7,
finetune_steps=100,
return_model=True # Return the fine-tuned parameters
)
# Save to file
import pickle
with open("fine_tuned_model.pkl", "wb") as f:
pickle.dump(fine_tuned_parameters, f)
# Load the fine-tuned parameters
import pickle
with open("fine_tuned_model.pkl", "rb") as f:
fine_tuned_parameters = pickle.load(f)
# Use the fine-tuned model
forecast = client.forecast(
new_df,
h=7,
model=fine_tuned_parameters
)
Need more help? Contact our support team.