---
title: "TimeGPT FAQ"
description: "Frequently asked questions about TimeGPT"
icon: "question"
---
Get started with TimeGPT in minutes
Set up the Python SDK for TimeGPT
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](https://dashboard.nixtla.io/). After confirming your signup via email, you can access your dashboard with account details.
Create an account at [dashboard.nixtla.io](https://dashboard.nixtla.io/)
Click the confirmation link in your email
Find your API key in the dashboard under "API Keys"
Run `pip install nixtla` to install the Python SDK
For a deeper understanding of TimeGPT, refer to the [research paper](https://arxiv.org/pdf/2310.03589.pdf). While some aspects of the model architecture remain confidential, registration for TimeGPT is open to everyone.
You can use TimeGPT through the Python SDK or the REST API.
```python Python SDK Forecast Example
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)
```
```bash REST API Forecast Example
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](https://dashboard.nixtla.io/) under "API Keys". Keep your API key confidential.
To integrate your API key into your development workflow, refer to the [Setting Up Your API Key](/setup/setting_up_your_api_key) tutorial.
```python Python API Key Example
from nixtla import NixtlaClient
client = NixtlaClient(api_key="your_api_key")
```
```bash REST API Key Example
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}'
```
Check your API key status with the [`validate_api_key` method](https://nixtlaverse.nixtla.io/nixtla/nixtla_client.html#nixtlaclient-validate-api-key) of the `NixtlaClient` class.
```python Validate API Key Example
from nixtla import NixtlaClient
nixtla_client = NixtlaClient(api_key='my_api_key_provided_by_nixtla')
nixtla_client.validate_api_key()
```
```bash Log Output
INFO:nixtla.nixtla_client:Happy Forecasting! :), If you have questions or need support, please email support@nixtla.io
True
```
When you validate your API key and it returns `False`:
* If you are targeting an Azure endpoint, getting `False` from the `NixtlaClient.validate_api_key` method is expected. You can skip this step when targeting an Azure endpoint and proceed diretly to forecasting instead.
* If you are not taregting an Azure endpoint, then you should check the following:
* Make sure you are using the latest version of the SDK (Python or R).
* Check that your API key is active in your dashboard by visiting https://dashboard.nixtla.io/.
* Consider any firewalls your organization might have. There may be restricted access. If so, you can whitelist our endpoint https://api.nixtla.io/.
* To use Nixtla's API, you need to let your system know that our endpoint is ok, so it will let you access it. Whitelisting the endpoint isn't something that Nixtla can do on our side. It's something that needs to be done on the user's system. This is a bit of an [overview on whitelisting](https://www.csoonline.com/article/569493/whitelisting-explained-how-it-works-and-where-it-fits-in-a-security-program.html).
* If you work in an organization, please work with an IT team. They're likely the ones setting the security and you can talk with them to get it addressed. If you run your own systems, then it's something you should be able to update, depending on the system you're using.
At Nixtla, we take privacy and security very seriously. To ensure you understand our data policies, refer to these documents:
Our data privacy policies
Python SDK license
TimeGPT service terms
We offer a self-hosted version of TimeGPT, allowing you complete control over your data - your data never leaves your premises. You can either use [Docker](/setup/docker) or a [Python wheel file](/setup/python_wheel). If interested in these option, contact us at `support@nixtla.io`.
Common errors and warnings
```python Invalid API Key Error
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](https://dashboard.nixtla.io/).
```python Too Many Requests Error
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](https://dashboard.nixtla.io/).
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](https://nixtlaverse.nixtla.io/nixtla/nixtla_client.html#nixtlaclient-forecast) 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:
For technical questions or bugs
For general inquiries or support
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](https://www.theanalysisfactor.com/wide-and-long-data/#comments) with these necessary columns:
Timestamp in format `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`
The target variable to forecast
You can also pass a DataFrame with a DatetimeIndex without the `ds` column.
```python Example Input DataFrame
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)
```
```
ds y
0 2023-01-01 10
1 2023-01-02 12
2 2023-01-03 15
```
TimeGPT also works with [distributed dataframes](/forecasting/forecasting-at-scale/computing_at_scale) 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](/forecasting/timegpt_quickstart) tutorial.
```python Multiple Series Forecasting
# 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](/forecasting/exogenous-variables/numeric_features) tutorial. For incorporating calendar dates, the [Holidays and Special Dates](https://docs.nixtla.io/docs/tutorials-holidays_and_special_dates) tutorial might help. For categorical variables, refer to the [Categorical Variables](https://docs.nixtla.io/docs/tutorials-categorical_variables) tutorial.
```python Exogenous Variables Forecast
# 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, use cross-validation. See the full tutorial on [cross-validation](/forecasting/evaluation/cross_validation).
```python Historical Forecast
# Get in-sample predictions
historical_forecast = client.cross_validation(
df,
h=12,
n_windows=11 # Set as many windows as you want
)
```
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](/forecasting/model-version/longhorizon_model) 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](/anomaly_detection/real-time/introduction) tutorial.
```python Anomaly Detection Example
# Detect anomalies in time series
anomalies = client.detect_anomalies(df)
```
Yes. To learn how to use TimeGPT for cross-validation, refer to the [Cross-Validation](/forecasting/evaluation/cross_validation) tutorial.
```python Cross-Validation Example
# 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](/forecasting/probabilistic/prediction_intervals) and [Quantile Forecasts](/forecasting/probabilistic/quantiles) tutorials.
```python Prediction Intervals Example
# Generate prediction intervals
forecast_with_intervals = client.forecast(
df,
h=7,
level=[80, 90, 95] # Confidence levels
)
```
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](/forecasting/forecasting-at-scale/computing_at_scale), including [Spark](/forecasting/forecasting-at-scale/spark), [Ray](/forecasting/forecasting-at-scale/ray), and [Dask](/forecasting/forecasting-at-scale/dask).
```python Using Dask Example
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](/data_requirements/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](/forecasting/special-topics/irregular_timestamps) and [Dealing with Missing Values](/data_requirements/missing_values) tutorials.
The `NixtlaClient` class has a [`plot` method](/reference/sdk_reference#nixtlaclient-plot) for visualizing forecasts. This method works only in interactive environments such as Jupyter notebooks, not in Python scripts.
```python Plotting Forecast Example
# Plot forecast
client.plot(
historical_data=df,
forecast_data=forecast,
level=[80, 95] # Optional: show prediction intervals
)
```
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](/forecasting/improve_accuracy) 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.
```python Fine-tuning Example
# 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](/forecasting/fine-tuning/steps) and [fine-tuning with a specific loss function](/forecasting/fine-tuning/custom_loss) 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](/forecasting/fine-tuning/save_reuse_delete_finetuned_models).
```python Save Fine-tuned Model
# 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)
```
```python Load Fine-tuned Model
# 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](mailto:support@nixtla.io).