> ## 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.

# TimeGPT FAQ

> Frequently asked questions about TimeGPT

> [card] [Quick Start](https://nixtla.io/docs/forecasting/timegpt_quickstart.md)
>
> Get started with TimeGPT in minutes

> [card] [SDK Installation](https://nixtla.io/docs/setup/setting_up_your_api_key.md)
>
> Set up the Python SDK for TimeGPT

> [card] [Pricing](https://nixtla.io/docs/introduction/ways_to_get_access.md)
>
> Review subscription plans and pricing

## Commonly asked questions

> [tab] TimeGPT
>
> > [accordion] What is TimeGPT?
> >
> > 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.
>
> > [accordion] Is TimeGPT based on a Large Language Model (LLM)?
> >
> > > [!TIP]
> > >
> > > 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.
>
> > [accordion] How do I get started with TimeGPT?
> >
> > To get started with TimeGPT, see [Ways to get access](https://nixtla.io/docs/introduction/ways_to_get_access.md) and pick the option that fits you. After confirming your signup via email, you can access your dashboard with account details.
> >
> > **1. Sign up**
> >
> > Get access through [Ways to get access](https://nixtla.io/docs/introduction/ways_to_get_access.md)
> >
> > **2. Confirm email**
> >
> > Click the confirmation link in your email
> >
> > **3. Get API key**
> >
> > Find your API key in the dashboard under "API Keys"
> >
> > **4. Install SDK**
> >
> > Run `pip install nixtla` to install the Python SDK
>
> > [accordion] How accessible is TimeGPT and what are the usage costs?
> >
> > 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.
>
> > [accordion] How can I use TimeGPT?
> >
> > You can use TimeGPT through the Python SDK or the REST API.
> >
> > > [tab] Python SDK
> > >
> > > ```python Python SDK Forecast Example theme={null}
> > > 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)
> > > ```
> >
> > > [tab] REST API
> > >
> > > ```bash REST API Forecast Example theme={null}
> > > 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".

> [tab] API Key
>
> > [accordion] What is an API key?
> >
> > 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.
> >
> > > [!WARNING]
> > >
> > > Your API key is personal and should not be shared with anyone or exposed in client-side code.
>
> > [accordion] Where can I get an API key?
> >
> > Upon registration, you receive an API key available in your dashboard under "API Keys". Keep your API key confidential.
>
> > [accordion] How do I use my API key?
> >
> > To integrate your API key into your development workflow, refer to the [Setting Up Your API Key](https://nixtla.io/docs/setup/setting_up_your_api_key.md) tutorial.
> >
> > **Python API Key Usage**
> >
> > ```python Python API Key Example theme={null}
> > from nixtla import NixtlaClient
> >
> > client = NixtlaClient(api_key="your_api_key")
> > ```
> >
> > **REST API Key Usage**
> >
> > ```bash REST API Key Example theme={null}
> > 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}'
> > ```
>
> > [accordion] How can I check the status of my API key?
> >
> > 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 theme={null}
> > from nixtla import NixtlaClient
> >
> > nixtla_client = NixtlaClient(api_key='my_api_key_provided_by_nixtla')
> > nixtla_client.validate_api_key()
> > ```
> >
> > ```bash Log Output theme={null}
> > INFO:nixtla.nixtla_client:Happy Forecasting! :), If you have questions or need support, please email support@nixtla.io
> >
> > True
> > ```
>
> > [accordion] What if my API key isn't validating?
> >
> > 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 directly to forecasting instead.
> > * If you are not targeting 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.
> >   * Consider any firewalls your organization might have. There may be restricted access. If so, you can whitelist our endpoint [https://api.nixtla.io/](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.

> [tab] Privacy & Security
>
> > [accordion] How do you ensure the privacy and security of my data?
> >
> > At Nixtla, we take privacy and security very seriously. To ensure you understand our data policies, refer to these documents:
> >
> > > [card] [Privacy Notice](https://nixtla.io/docs/about/privacy-notice.md)
> > >
> > > Our data privacy policies
> >
> > > [card] [License Agreement](https://github.com/Nixtla/nixtla/blob/main/LICENSE)
> > >
> > > Python SDK license
> >
> > > [card] [Terms and Conditions](https://nixtla.io/docs/about/terms-and-conditions.md)
> > >
> > > TimeGPT service terms
> >
> > > [!NOTE]
> > >
> > > 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](https://nixtla.io/docs/setup/docker.md) or a [Python wheel file](https://nixtla.io/docs/setup/python_wheel.md). If interested in these option, contact us at `support@nixtla.io`.

> [tab] Troubleshooting
>
> ### Common errors and warnings
>
> > [accordion] Error message: Invalid API key
> >
> > ```python Invalid API Key Error theme={null}
> > 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'}
> > ```
> >
> > > [!NOTE]
> > >
> > > 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.
>
> > [accordion] Error message: Too many requests
> >
> > ```python Too Many Requests Error theme={null}
> > 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://www.nixtla.io/book-a-free-trial?utm_source=nixtla.io&utm_campaign=/docs/introduction/faq', 'code': 'A21', 'requestID': 'NCJDK7KSJ6', 'support': 'If you have questions or need support, please email support@nixtla.io'}
> > ```
> >
> > > [!NOTE]
> > >
> > > This error occurs when you have used all of your free API calls. To continue using TimeGPT, contact us at [support@nixtla.io](mailto:support@nixtla.io) and our team will help with a paid plan.
>
> > [accordion] Error message: WriteTimeout
> >
> > > [!NOTE]
> > >
> > > 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.

> [tab] Support
>
> Get Help with TimeGPT
> For more questions or support, reach out through one of our channels:
>
> > [card] [GitHub Issues](https://github.com/Nixtla/nixtla/issues)
> >
> > For technical questions or bugs
>
> > [card] [Email Support](mailto:support@nixtla.io)
> >
> > For general inquiries or support
>
> > [card] [Slack Community](https://join.slack.com/t/nixtlacommunity/shared_invite/zt-2ebtgjbip-QMSnvm6ED1NF5vi4xj_13Q)
> >
> > Connect with our team and community
>
> > [!TIP]
> >
> > When reporting issues, include your API key status, SDK version, and sample code to help us assist you more quickly.

## Features & Capabilities

> [tab] Input Data
>
> > [accordion] What is the input to TimeGPT?
> >
> > 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
> >
> > > [!TIP]
> > >
> > > You can also pass a DataFrame with a DatetimeIndex without the `ds` column.
> >
> > **Example Input DataFrame**
> >
> > ```python Example Input DataFrame theme={null}
> > 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)
> > ```
> >
> > **Printed DataFrame Output**
> >
> > ```
> >          ds   y
> > 0 2023-01-01  10
> > 1 2023-01-02  12
> > 2 2023-01-03  15
> > ```
> >
> > TimeGPT also works with [distributed dataframes](https://nixtla.io/docs/forecasting/forecasting-at-scale/computing_at_scale.md) like `dask`, `spark`, and `ray`.
>
> > [accordion] Can TimeGPT handle multiple time series?
> >
> > > [!TIP]
> > >
> > > Yes, TimeGPT can forecast multiple time series simultaneously.
> >
> > For guidance on forecasting multiple time series at once, consult the [Multiple Series](https://nixtla.io/docs/forecasting/timegpt_quickstart.md) tutorial.
> >
> > **Multiple Series Forecasting Example**
> >
> > ```python Multiple Series Forecasting theme={null}
> > # 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])
> > ```

> [tab] Forecasting
>
> > [accordion] Does TimeGPT support forecasting with exogenous variables?
> >
> > > [!TIP]
> > >
> > > Yes, TimeGPT can incorporate external variables into forecasts.
> >
> > For instructions on incorporating exogenous variables to TimeGPT, see the [Exogenous Variables](https://nixtla.io/docs/forecasting/exogenous-variables/numeric_features.md) 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.
> >
> > **Exogenous Variables Forecast Example**
> >
> > ```python Exogenous Variables Forecast theme={null}
> > # Forecasting with exogenous variables
> > forecast = client.forecast(
> >     df,
> >     h=7,
> >     X_df=exog_df  # DataFrame with exogenous variables
> > )
> > ```
>
> > [accordion] Can TimeGPT be used to forecast historical data?
> >
> > Yes. To forecast historical data using TimeGPT, use cross-validation. See the full tutorial on [cross-validation](https://nixtla.io/docs/forecasting/evaluation/cross_validation.md).
> >
> > **Historical Forecast Example**
> >
> > ```python Historical Forecast theme={null}
> > # Get in-sample predictions
> > historical_forecast = client.cross_validation(
> >     df,
> >     h=12,
> >     n_windows=11 # Set as many windows as you want
> > )
> > ```
>
> > [accordion] What is the maximum forecast horizon allowed by TimeGPT?
> >
> > 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:
> >
> > > [!NOTE]
> > >
> > > `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](https://nixtla.io/docs/forecasting/model-version/longhorizon_model.md) tutorial.
> >
> > > [!TIP]
> > >
> > > For best results, keep your forecast horizon within the seasonal pattern of your data.

> [tab] Advanced Features
>
> > [accordion] Can TimeGPT be used for anomaly detection?
> >
> > > [!TIP]
> > >
> > > Yes, TimeGPT includes anomaly detection capabilities.
> >
> > To learn how to use TimeGPT for anomaly detection, refer to the [Anomaly Detection](https://nixtla.io/docs/anomaly_detection/real-time/introduction.md) tutorial.
> >
> > **Anomaly Detection Example**
> >
> > ```python Anomaly Detection Example theme={null}
> > # Detect anomalies in time series
> > anomalies = client.detect_anomalies(df)
> > ```
>
> > [accordion] Does TimeGPT support cross-validation?
> >
> > Yes. To learn how to use TimeGPT for cross-validation, refer to the [Cross-Validation](https://nixtla.io/docs/forecasting/evaluation/cross_validation.md) tutorial.
> >
> > **Cross-Validation Example**
> >
> > ```python Cross-Validation Example theme={null}
> > # Perform cross-validation
> > cv_results = client.cross_validation(
> >     df,
> >     h=7,
> >     k=3,  # Number of folds
> >     test_size=7  # Size of each test fold
> > )
> > ```
>
> > [accordion] Can TimeGPT be used for uncertainty quantification?
> >
> > Yes. For more information, explore the [Prediction Intervals](https://nixtla.io/docs/forecasting/probabilistic/prediction_intervals.md) and [Quantile Forecasts](https://nixtla.io/docs/forecasting/probabilistic/quantiles.md) tutorials.
> >
> > **Prediction Intervals Example**
> >
> > ```python Prediction Intervals Example theme={null}
> > # Generate prediction intervals
> > forecast_with_intervals = client.forecast(
> >     df,
> >     h=7,
> >     level=[80, 90, 95]  # Confidence levels
> > )
> > ```

> [tab] Data Requirements
>
> > [accordion] Can TimeGPT handle large datasets?
> >
> > > [!TIP]
> > >
> > > 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](https://nixtla.io/docs/forecasting/forecasting-at-scale/computing_at_scale.md), including [Spark](https://nixtla.io/docs/forecasting/forecasting-at-scale/spark.md), [Ray](https://nixtla.io/docs/forecasting/forecasting-at-scale/ray.md), and [Dask](https://nixtla.io/docs/forecasting/forecasting-at-scale/dask.md).
> >
> > **Using Dask for Large Datasets**
> >
> > ```python Using Dask Example theme={null}
> > 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)
> > ```
>
> > [accordion] Can TimeGPT be used with limited/short data?
> >
> > 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](https://nixtla.io/docs/data_requirements/data_requirements.md) tutorial.
> >
> > > [!NOTE]
> > >
> > > While TimeGPT can work with minimal data, more historical data typically produces better forecasts.
>
> > [accordion] Can TimeGPT handle missing values?
> >
> > > [!WARNING]
> > >
> > > TimeGPT cannot handle missing values or series with irregular timestamps.
> >
> > For more information, see the [Forecasting Time Series with Irregular Timestamps](https://nixtla.io/docs/forecasting/special-topics/irregular_timestamps.md) and [Dealing with Missing Values](https://nixtla.io/docs/data_requirements/missing_values.md) tutorials.

> [tab] Visualization
>
> > [accordion] How can I plot the TimeGPT forecast?
> >
> > The `NixtlaClient` class has a [`plot` method](https://nixtla.io/docs/reference/sdk_reference#nixtlaclient-plot) for visualizing forecasts. This method works only in interactive environments such as Jupyter notebooks, not in Python scripts.
> >
> > **Plotting Forecast Example**
> >
> > ```python Plotting Forecast Example theme={null}
> > # Plot forecast
> > client.plot(
> >     historical_data=df,
> >     forecast_data=forecast,
> >     level=[80, 95]  # Optional: show prediction intervals
> > )
> > ```
>
> > [accordion] Does TimeGPT support polars?
> >
> > Currently, TimeGPT does not support polars.
>
> > [accordion] Does TimeGPT produce stable predictions?
> >
> > > [!TIP]
> > >
> > > 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.
>
> > [accordion] Can TimeGPT forecast data with simple pattern such as a straight line or sine wave?
> >
> > 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](https://nixtla.io/docs/forecasting/improve_accuracy.md) tutorial.

> [tab] Fine-tuning
>
> > [accordion] What is fine-tuning?
> >
> > > [!TIP]
> > >
> > > 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 Usage Example**
> >
> > ```python Fine-tuning Example theme={null}
> > # 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](https://nixtla.io/docs/forecasting/fine-tuning/steps.md) and [fine-tuning with a specific loss function](https://nixtla.io/docs/forecasting/fine-tuning/custom_loss.md) tutorials.
>
> > [accordion] Do I have to fine-tune every series?
> >
> > 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.
> >
> > > [!NOTE]
> > >
> > > 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.
>
> > [accordion] Can I save fine-tuned parameters?
> >
> > > [!TIP]
> > >
> > > 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](https://nixtla.io/docs/forecasting/fine-tuning/save_reuse_delete_finetuned_models.md).
> >
> > > [tab] Save Model
> > >
> > > ```python Save Fine-tuned Model theme={null}
> > > # 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)
> > > ```
> >
> > > [tab] Load Model
> > >
> > > ```python Load Fine-tuned Model theme={null}
> > > # 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
> > > )
> > > ```

> [!NOTE]
>
> Need more help? Contact our [support team](mailto:support@nixtla.io).