source

NixtlaClient

 NixtlaClient (api_key:Optional[str]=None, base_url:Optional[str]=None,
               timeout:Optional[int]=60, max_retries:int=6,
               retry_interval:int=10, max_wait_time:int=360)

Client to interact with the Nixtla API.

	Type	Default	Details
api_key	Optional	None	The authorization api_key interacts with the Nixtla API. If not provided, will use the NIXTLA_API_KEY environment variable.
base_url	Optional	None	Custom base_url. If not provided, will use the NIXTLA_BASE_URL environment variable.
timeout	Optional	60	Request timeout in seconds. Set this to `None` to disable it.
max_retries	int	6	The maximum number of attempts to make when calling the API before giving up. It defines how many times the client will retry the API call if it fails. Default value is 6, indicating the client will attempt the API call up to 6 times in total. Job submissions, including `execute_step`, retry only connection failures and HTTP 429. Read timeouts and gateway errors are not retried because the server may already have accepted the job.
retry_interval	int	10	The interval in seconds between consecutive retry attempts. This is the waiting period before the client tries to call the API again after a failed attempt. Default value is 10 seconds, meaning the client waits for 10 seconds between retries.
max_wait_time	int	360	The maximum total time in seconds that the client will spend on all retry attempts before giving up. This sets an upper limit on the cumulative waiting time for all retry attempts. If this time is exceeded, the client will stop retrying and raise an exception. Default value is 360 seconds, meaning the client will cease retrying if the total time spent on retries exceeds 360 seconds. The client throws a ReadTimeout error after 60 seconds of inactivity. If you want to catch these errors, use max_wait_time >> 60.

How long the client waits for a server-side asynchronous job is set per call, not on the client: pass poll_interval and poll_timeout to simulate(), explain(), or Job.wait(). By default polling is adaptive — the first status check comes after half a second and the interval doubles up to one check every 15 seconds — under a one-hour ceiling. An explicit poll_interval is a fixed cadence instead, and poll_timeout=None waits until the server reports a terminal status. The submit_*_job methods below submit the same work without waiting for it, returning a Job handle. Async partitioned requests run at most five jobs concurrently. A partition failure cancels sibling jobs and stops queued submissions. Synchronous partitioned requests also stop queued work after a failure. Submission retry sleeps, including Retry-After, are limited to the remaining max_wait_time budget; no further attempt starts once it expires. An in-flight request remains governed by the HTTP timeout.

source

NixtlaClient.validate_api_key

 NixtlaClient.validate_api_key (log:bool=True)

Check API key status.

	Type	Default	Details
log	bool	True	Show the endpoint’s response.
Returns	bool		Whether API key is valid.

source

NixtlaClient.forecast

NixtlaClient.forecast (
    df, h, freq=None, id_col="unique_id", time_col="ds",
    target_col="y", X_df=None, level=None, quantiles=None,
    finetune_steps=0, finetune_depth=1, finetune_loss="default",
    finetuned_model_id=None, clean_ex_first=True,
    hist_exog_list=None, categorical_exog_list=None,
    validate_api_key=False, add_history=False, date_features=False,
    date_features_to_one_hot=False, model="timegpt-2.1",
    num_partitions=None, feature_contributions=False,
    model_parameters=None, multivariate=False,
    feature_contributions_type="shapley"
)

Forecast your time series using TimeGPT.

	Type	Default	Details
df	AnyDFType		The DataFrame on which the function will operate. Expected to contain at least the following columns: - time_col: Column name in `df` that contains the time indices of the time series. This is typically a datetime column with regular intervals, e.g., hourly, daily, monthly data points. - target_col: Column name in `df` that contains the target variable of the time series, i.e., the variable we wish to predict or analyze. Additionally, you can pass multiple time series (stacked in the dataframe) considering an additional column: - id_col: Column name in `df` that identifies unique time series. Each unique value in this column corresponds to a unique time series.
h	Annotated		Forecast horizon.
freq	Union	None	Frequency of the timestamps. If `None`, it will be inferred automatically. See pandas’ available frequencies.
id_col	str	unique_id	Column that identifies each series.
time_col	str	ds	Column that identifies each timestep, its values can be timestamps or integers.
target_col	str	y	Column that contains the target.
X_df	Optional	None	DataFrame with [`unique_id`, `ds`] columns and `df`’s future exogenous.
level	Optional	None	Confidence levels between 0 and 100 for prediction intervals.
quantiles	Optional	None	Quantiles to forecast, list between (0, 1). `level` and `quantiles` should not be used simultaneously. The output dataframe will have the quantile columns formatted as TimeGPT-q-(100 * q) for each q. 100 * q represents percentiles but we choose this notation to avoid having dots in column names.
finetune_steps	Annotated	0	Number of steps used to finetune learning TimeGPT in the new data.
finetune_depth	Literal	1	The depth of the finetuning. Uses a scale from 1 to 5, where 1 means little finetuning, and 5 means that the entire model is finetuned.
finetune_loss	Literal	default	Loss function to use for finetuning. Options are: `default`, `mae`, `mse`, `rmse`, `mape`, and `smape`.
finetuned_model_id	Optional	None	ID of previously fine-tuned model to use.
clean_ex_first	bool	True	Clean exogenous signal before making forecasts using TimeGPT.
hist_exog_list	Optional	None	Column names of the historical exogenous features.
categorical_exog_list	Optional	None	Column names of categorical exogenous features.
validate_api_key	bool	False	If True, validates api_key before sending requests.
add_history	bool	False	Return fitted values of the model.
date_features	Union	False	Features computed from the dates. Can be pandas date attributes or functions that will take the dates as input. If True automatically adds most used date features for the frequency of `df`.
date_features_to_one_hot	Union	False	Apply one-hot encoding to these date features. If `date_features=True`, then all date features are one-hot encoded by default.
model	str	timegpt-2.1	Model to use. Available models depend on your account.
num_partitions	Optional	None	Number of partitions to use. If None, the number of partitions will be equal to the available parallel resources in distributed environments.
feature_contributions	bool	False	Compute feature contributions and store them in `NixtlaClient.feature_contributions`.
model_parameters	Optional	None	Optional model-specific settings.
multivariate	bool	False	Enable multivariate predictions for models that support them.
feature_contributions_type	Literal	shapley	Explanation used for feature contributions. Options are `shapley`, `intervention`, `granger`, and `transfer_entropy`.
Returns	AnyDFType		DataFrame with TimeGPT forecasts for point predictions and probabilistic predictions (if level is not None).

source

NixtlaClient.simulate

NixtlaClient.simulate (
    df, h, freq=None, id_col="unique_id", time_col="ds",
    target_col="y", X_df=None, n_paths=100, quantiles=None,
    seed=None, finetuned_model_id=None, clean_ex_first=True,
    hist_exog_list=None, categorical_exog_list=None,
    validate_api_key=False, date_features=False,
    date_features_to_one_hot=False, model="timegpt-2.1",
    multivariate=False, num_partitions=None,
    job_timeout_seconds=None, poll_interval=None, poll_timeout=3600.0
)

Generate temporally correlated forecast sample paths. The request runs as an asynchronous job on the server: the client submits it, then polls its status until it finishes, so the call blocks until the paths are available. Use poll_interval and poll_timeout to control the waiting behavior, or NixtlaClient.submit_simulate_job to get a Job handle back immediately. A job that fails on the server raises nixtla.AsyncJobError. If the job outlives poll_timeout, the client requests cancellation and raises nixtla.AsyncJobTimeoutError. Server-side cancellation raises nixtla.AsyncJobCancelledError. Invalid inputs, including missing or duplicate timestamps, raise ValueError. HTTP failures raise nixtla.ApiError, preserving the server’s error body.

	Type	Default	Details
df	pandas or polars DataFrame		Historical time-series data containing the time and target columns. It may also contain an ID column and exogenous features.
h	int		Number of future timesteps in every path. Must be greater than zero.
freq	str, int, or pandas offset	None	Frequency of the timestamps. If `None`, it is inferred from `df` (pandas only); pass it explicitly for polars.
id_col	str	unique_id	Column that identifies each series.
time_col	str	ds	Column that identifies each timestep.
target_col	str	y	Column that contains the target.
X_df	pandas or polars DataFrame	None	Future exogenous values with the ID and time columns.
n_paths	int	100	Number of paths returned for each series. Must be between 1 and 10,000.
quantiles	list[float]	None	Strictly increasing quantile grid inside `(0, 1)`. The list must contain between 2 and 200 values.
seed	int	None	Random seed between `-263` and `264 - 1`. Reusing a seed with identical inputs returns identical paths.
finetuned_model_id	str	None	ID of a previously fine-tuned model.
clean_ex_first	bool	True	Clean exogenous signals before inference.
hist_exog_list	list[str]	None	Names of historical-only exogenous features.
categorical_exog_list	list[str]	None	Names of categorical exogenous features.
validate_api_key	bool	False	Validate the API key before sending the request.
date_features	bool or list	False	Date-derived exogenous features to add.
date_features_to_one_hot	bool or list[str]	False	Date features to one-hot encode.
model	str	timegpt-2.1	Model used to generate the forecasts.
multivariate	bool	False	Request coherent paths across series. The returned `coupled` column reports whether cross-series coupling was applied.
num_partitions	int	None	Split the series across this many concurrent requests to keep large jobs under the request size limit. Cannot be combined with `multivariate=True`. Each partition receives a distinct seed derived from `seed`, so the call stays reproducible, but a partitioned call returns different paths than an unpartitioned one for the same `seed`.
job_timeout_seconds	int	None	Maximum time in seconds the server may spend on the job (on each partition when `num_partitions` is set). It may not exceed the limit of the deployment. Defaults to the deployment’s limit.
poll_interval	float	None	Seconds between two status checks of the job, held fixed. By default the client polls on an adaptive cadence instead: the first check comes after half a second and the interval doubles up to one check every 15 seconds, so a short job returns promptly and a long one still polls cheaply.
poll_timeout	float	3600.0	Maximum seconds to wait for the job to reach a terminal state, measured from a successful submission and including queueing time on the server. Submission retries are excluded; each partition gets its own timeout. When it elapses the client requests cancellation and raises `AsyncJobTimeoutError`. Set to `None` to wait until the server reports a terminal status.
Returns	pandas or polars DataFrame		*Long-form paths containing the ID and time columns, `sample_id`, `TimeGPT`, and `coupled`. The dataframe contains `n_series n_paths * h` rows. The ID column is omitted if `df` did not contain one.**

See Forecast Simulation for complete examples, output interpretation, limits, and scenario analysis.

source

NixtlaClient.explain

NixtlaClient.explain (
    df, method="granger", features=None, freq=None,
    id_col="unique_id", time_col="ds", target_col="y",
    categorical_exog_list=None, validate_api_key=False,
    job_timeout_seconds=None, poll_interval=None, poll_timeout=3600.0
)

Compute model-independent historical feature importance weights. The request runs as an asynchronous job on the server: the client submits it, then polls its status until it finishes, so the call blocks until the weights are available. Use poll_interval and poll_timeout to control the waiting behavior, or NixtlaClient.submit_explain_job to get a Job handle back immediately. A job that fails on the server raises nixtla.AsyncJobError. If the job outlives poll_timeout, the client requests cancellation and raises nixtla.AsyncJobTimeoutError. Server-side cancellation raises nixtla.AsyncJobCancelledError. Invalid inputs, including missing or duplicate timestamps, raise ValueError. HTTP failures raise nixtla.ApiError, preserving the server’s error body.

	Type	Default	Details
df	pandas or polars DataFrame		Historical time-series data containing the target and candidate feature columns.
method	str	granger	Analysis to run. Use `"granger"` for linear lagged relationships or `"transfer_entropy"` for potentially nonlinear relationships.
features	list[str]	None	Features to analyze. By default, every column other than the ID, time, and target columns is used. Non-numeric features must be listed in `categorical_exog_list`.
freq	str, int or pandas offset	None	Frequency of the timestamps, used to verify that every series is complete and regularly spaced. Both methods are lag-based, so gaps or duplicate timestamps distort the weights. Inferred from `df` when None; required for polars.
id_col	str	unique_id	Column that identifies each series.
time_col	str	ds	Column that identifies each timestep.
target_col	str	y	Column that contains the target.
categorical_exog_list	list[str]	None	Feature names to treat as categorical. Every name must also appear in `features`.
validate_api_key	bool	False	Validate the API key before sending the request.
job_timeout_seconds	int	None	Maximum time in seconds the server may spend on the job. It may not exceed the limit of the deployment. Defaults to the deployment’s limit.
poll_interval	float	None	Seconds between two status checks of the job, held fixed. By default the client polls on an adaptive cadence instead: the first check comes after half a second and the interval doubles up to one check every 15 seconds, so a short job returns promptly and a long one still polls cheaply.
poll_timeout	float	3600.0	Maximum seconds to wait for the job to reach a terminal state, measured from a successful submission and including queueing time on the server. When it elapses the client requests cancellation and raises `AsyncJobTimeoutError`. Set to `None` to wait until the server reports a terminal status.
Returns	pandas or polars DataFrame		One row per feature with `feature`, `weight`, and `method` columns. Weights are nonnegative and sum to one.

The weights describe predictive relationships in historical data; they do not establish causality. See Find predictive signals in history for interpretation guidance and examples.

source

NixtlaClient.cross_validation

 NixtlaClient.cross_validation (df:~AnyDFType,
                                h:typing.Annotated[int,Gt(gt=0)], freq:Uni
                                on[str,int,pandas._libs.tslibs.offsets.Bas
                                eOffset,NoneType]=None,
                                id_col:str='unique_id', time_col:str='ds',
                                target_col:str='y', level:Optional[list[Un
                                ion[int,float]]]=None,
                                quantiles:Optional[list[float]]=None,
                                validate_api_key:bool=False, n_windows:typ
                                ing.Annotated[int,Gt(gt=0)]=1, step_size:O
                                ptional[Annotated[int,Gt(gt=0)]]=None, fin
                                etune_steps:typing.Annotated[int,Ge(ge=0)]
                                =0, finetune_depth:Literal[1,2,3,4,5]=1, f
                                inetune_loss:Literal['default','mae','mse'
                                ,'rmse','mape','smape']='default',
                                finetuned_model_id:Optional[str]=None,
                                refit:bool=True, clean_ex_first:bool=True,
                                hist_exog_list:Optional[list[str]]=None,
                                date_features:Union[bool,list[str]]=False,
                                date_features_to_one_hot:Union[bool,list[s
                                tr]]=False, model:Literal['azureai','timeg
                                pt-1','timegpt-1-long-
                                horizon']='timegpt-1', num_partitions:Opti
                                onal[Annotated[int,Gt(gt=0)]]=None)

Perform cross validation in your time series using TimeGPT.

	Type	Default	Details
df	AnyDFType		The DataFrame on which the function will operate. Expected to contain at least the following columns: - time_col: Column name in `df` that contains the time indices of the time series. This is typically a datetime column with regular intervals, e.g., hourly, daily, monthly data points. - target_col: Column name in `df` that contains the target variable of the time series, i.e., the variable we wish to predict or analyze. Additionally, you can pass multiple time series (stacked in the dataframe) considering an additional column: - id_col: Column name in `df` that identifies unique time series. Each unique value in this column corresponds to a unique time series.
h	Annotated		Forecast horizon.
freq	Union	None	Frequency of the timestamps. If `None`, it will be inferred automatically. See pandas’ available frequencies.
id_col	str	unique_id	Column that identifies each series.
time_col	str	ds	Column that identifies each timestep, its values can be timestamps or integers.
target_col	str	y	Column that contains the target.
level	Optional	None	Confidence level between 0 and 100 for prediction intervals.
quantiles	Optional	None	Quantiles to forecast, list between (0, 1). `level` and `quantiles` should not be used simultaneously. The output dataframe will have the quantile columns formatted as TimeGPT-q-(100 * q) for each q. 100 * q represents percentiles but we choose this notation to avoid having dots in column names.
validate_api_key	bool	False	If True, validates api_key before sending requests.
n_windows	Annotated	1	Number of windows to evaluate.
step_size	Optional	None	Step size between each cross validation window. If None it will be equal to `h`.
finetune_steps	Annotated	0	Number of steps used to finetune TimeGPT in the new data.
finetune_depth	Literal	1	The depth of the finetuning. Uses a scale from 1 to 5, where 1 means little finetuning, and 5 means that the entire model is finetuned.
finetune_loss	Literal	default	Loss function to use for finetuning. Options are: `default`, `mae`, `mse`, `rmse`, `mape`, and `smape`.
finetuned_model_id	Optional	None	ID of previously fine-tuned model to use.
refit	bool	True	Fine-tune the model in each window. If `False`, only fine-tunes on the first window. Only used if `finetune_steps` > 0.
clean_ex_first	bool	True	Clean exogenous signal before making forecasts using TimeGPT.
hist_exog_list	Optional	None	Column names of the historical exogenous features.
date_features	Union	False	Features computed from the dates. Can be pandas date attributes or functions that will take the dates as input. If True automatically adds most used date features for the frequency of `df`.
date_features_to_one_hot	Union	False	Apply one-hot encoding to these date features. If `date_features=True`, then all date features are one-hot encoded by default.
model	Literal	timegpt-1	Model to use as a string. Options are: `timegpt-1`, and `timegpt-1-long-horizon`. We recommend using `timegpt-1-long-horizon` for forecasting if you want to predict more than one seasonal period given the frequency of your data.
num_partitions	Optional	None	Number of partitions to use. If None, the number of partitions will be equal to the available parallel resources in distributed environments.
Returns	AnyDFType		DataFrame with cross validation forecasts.

source

NixtlaClient.detect_anomalies

 NixtlaClient.detect_anomalies (df:~AnyDFType,
                                freq:Union[str,int,pandas._libs.tslibs.off
                                sets.BaseOffset,NoneType]=None,
                                id_col:str='unique_id', time_col:str='ds',
                                target_col:str='y',
                                level:Union[int,float]=99,
                                finetuned_model_id:Optional[str]=None,
                                clean_ex_first:bool=True,
                                validate_api_key:bool=False,
                                date_features:Union[bool,list[str]]=False,
                                date_features_to_one_hot:Union[bool,list[s
                                tr]]=False, model:Literal['azureai','timeg
                                pt-1','timegpt-1-long-
                                horizon']='timegpt-1', num_partitions:Opti
                                onal[Annotated[int,Gt(gt=0)]]=None)

Detect anomalies in your time series using TimeGPT.

	Type	Default	Details
df	AnyDFType		The DataFrame on which the function will operate. Expected to contain at least the following columns: - time_col: Column name in `df` that contains the time indices of the time series. This is typically a datetime column with regular intervals, e.g., hourly, daily, monthly data points. - target_col: Column name in `df` that contains the target variable of the time series, i.e., the variable we wish to predict or analyze. Additionally, you can pass multiple time series (stacked in the dataframe) considering an additional column: - id_col: Column name in `df` that identifies unique time series. Each unique value in this column corresponds to a unique time series.
freq	Union	None	Frequency of the timestamps. If `None`, it will be inferred automatically. See pandas’ available frequencies.
id_col	str	unique_id	Column that identifies each series.
time_col	str	ds	Column that identifies each timestep, its values can be timestamps or integers.
target_col	str	y	Column that contains the target.
level	Union	99	Confidence level between 0 and 100 for detecting the anomalies.
finetuned_model_id	Optional	None	ID of previously fine-tuned model to use.
clean_ex_first	bool	True	Clean exogenous signal before making forecasts using TimeGPT.
validate_api_key	bool	False	If True, validates api_key before sending requests.
date_features	Union	False	Features computed from the dates. Can be pandas date attributes or functions that will take the dates as input. If True automatically adds most used date features for the frequency of `df`.
date_features_to_one_hot	Union	False	Apply one-hot encoding to these date features. If `date_features=True`, then all date features are one-hot encoded by default.
model	Literal	timegpt-1	Model to use as a string. Options are: `timegpt-1`, and `timegpt-1-long-horizon`. We recommend using `timegpt-1-long-horizon` for forecasting if you want to predict more than one seasonal period given the frequency of your data.
num_partitions	Optional	None	Number of partitions to use. If None, the number of partitions will be equal to the available parallel resources in distributed environments.
Returns	AnyDFType		DataFrame with anomalies flagged by TimeGPT.

source

NixtlaClient.usage

 NixtlaClient.usage ()

Query consumed requests and limits

source

NixtlaClient.list_models

 NixtlaClient.list_models ()

List the models available to your API key.

	Type	Details
Returns	list	Model names, sorted. Each can be passed as the `model` argument of `forecast`, `cross_validation`, `detect_anomalies` and the other forecasting methods; a model absent from this list is one those methods would reject.

source

NixtlaClient.finetune

 NixtlaClient.finetune
                        (df:Union[pandas.core.frame.DataFrame,polars.dataf
                        rame.frame.DataFrame], freq:Union[str,int,pandas._
                        libs.tslibs.offsets.BaseOffset,NoneType]=None,
                        id_col:str='unique_id', time_col:str='ds',
                        target_col:str='y',
                        finetune_steps:typing.Annotated[int,Ge(ge=0)]=10,
                        finetune_depth:Literal[1,2,3,4,5]=1, finetune_loss
                        :Literal['default','mae','mse','rmse','mape','smap
                        e']='default', output_model_id:Optional[str]=None,
                        finetuned_model_id:Optional[str]=None, model:Liter
                        al['azureai','timegpt-1','timegpt-1-long-
                        horizon']='timegpt-1')

Fine-tune TimeGPT to your series.

	Type	Default	Details
df	Union		The DataFrame on which the function will operate. Expected to contain at least the following columns: - time_col: Column name in `df` that contains the time indices of the time series. This is typically a datetime column with regular intervals, e.g., hourly, daily, monthly data points. - target_col: Column name in `df` that contains the target variable of the time series, i.e., the variable we wish to predict or analyze. Additionally, you can pass multiple time series (stacked in the dataframe) considering an additional column: - id_col: Column name in `df` that identifies unique time series. Each unique value in this column corresponds to a unique time series.
freq	Union	None	Frequency of the timestamps. If `None`, it will be inferred automatically. See pandas’ available frequencies.
id_col	str	unique_id	Column that identifies each series.
time_col	str	ds	Column that identifies each timestep, its values can be timestamps or integers.
target_col	str	y	Column that contains the target.
finetune_steps	Annotated	10	Number of steps used to finetune learning TimeGPT in the new data.
finetune_depth	Literal	1	The depth of the finetuning. Uses a scale from 1 to 5, where 1 means little finetuning, and 5 means that the entire model is finetuned.
finetune_loss	Literal	default	Loss function to use for finetuning. Options are: `default`, `mae`, `mse`, `rmse`, `mape`, and `smape`.
output_model_id	Optional	None	ID to assign to the fine-tuned model. If `None`, an UUID is used.
finetuned_model_id	Optional	None	ID of previously fine-tuned model to use as base.
model	Literal	timegpt-1	Model to use as a string. Options are: `timegpt-1`, and `timegpt-1-long-horizon`. We recommend using `timegpt-1-long-horizon` for forecasting if you want to predict more than one seasonal period given the frequency of your data.
Returns	str		ID of the fine-tuned model

source

NixtlaClient.finetuned_models

 NixtlaClient.finetuned_models (as_df:bool=False)

List fine-tuned models

	Type	Default	Details
as_df	bool	False	Return the fine-tuned models as a pandas dataframe
Returns	Union		List of available fine-tuned models.

source

NixtlaClient.finetuned_model

 NixtlaClient.finetuned_model (finetuned_model_id:str)

Get fine-tuned model metadata

	Type	Details
finetuned_model_id	str	ID of the fine-tuned model to get metadata from.
Returns	FinetunedModel	Fine-tuned model metadata.

source

NixtlaClient.delete_finetuned_model

 NixtlaClient.delete_finetuned_model (finetuned_model_id:str)

Delete a previously fine-tuned model

	Type	Details
finetuned_model_id	str	ID of the fine-tuned model to be deleted.
Returns	bool	Whether delete was successful.

source

NixtlaClient.plot

 NixtlaClient.plot (df:Union[pandas.core.frame.DataFrame,polars.dataframe.
                    frame.DataFrame,NoneType]=None, forecasts_df:Union[pan
                    das.core.frame.DataFrame,polars.dataframe.frame.DataFr
                    ame,NoneType]=None, id_col:str='unique_id',
                    time_col:str='ds', target_col:str='y', unique_ids:Unio
                    n[list[str],NoneType,numpy.ndarray]=None,
                    plot_random:bool=True, max_ids:int=8,
                    models:Optional[list[str]]=None,
                    level:Optional[list[Union[int,float]]]=None,
                    max_insample_length:Optional[int]=None,
                    plot_anomalies:bool=False,
                    engine:Literal['matplotlib','plotly','plotly-
                    resampler']='matplotlib',
                    resampler_kwargs:Optional[dict]=None, ax:Union[Forward
                    Ref('plt.Axes'),numpy.ndarray,ForwardRef('plotly.graph
                    _objects.Figure'),NoneType]=None)

Plot forecasts and insample values.

	Type	Default	Details
df	Union	None	The DataFrame on which the function will operate. Expected to contain at least the following columns: - time_col: Column name in `df` that contains the time indices of the time series. This is typically a datetime column with regular intervals, e.g., hourly, daily, monthly data points. - target_col: Column name in `df` that contains the target variable of the time series, i.e., the variable we wish to predict or analyze. Additionally, you can pass multiple time series (stacked in the dataframe) considering an additional column: - id_col: Column name in `df` that identifies unique time series. Each unique value in this column corresponds to a unique time series.
forecasts_df	Union	None	DataFrame with columns [`unique_id`, `ds`] and models.
id_col	str	unique_id	Column that identifies each series.
time_col	str	ds	Column that identifies each timestep, its values can be timestamps or integers.
target_col	str	y	Column that contains the target.
unique_ids	Union	None	Time Series to plot. If None, time series are selected randomly.
plot_random	bool	True	Select time series to plot randomly.
max_ids	int	8	Maximum number of ids to plot.
models	Optional	None	list of models to plot.
level	Optional	None	list of prediction intervals to plot if passed.
max_insample_length	Optional	None	Max number of train/insample observations to be plotted.
plot_anomalies	bool	False	Plot anomalies for each prediction interval.
engine	Literal	matplotlib	Library used to plot. ‘matplotlib’, ‘plotly’ or ‘plotly-resampler’.
resampler_kwargs	Optional	None	Kwargs to be passed to plotly-resampler constructor. For further customization (“show_dash”) call the method, store the plotting object and add the extra arguments to its `show_dash` method.
ax	Union	None	Object where plots will be added.

Asynchronous jobs

Every long-running task can be started without waiting for it. The submit_*_job methods below send the same request their blocking counterparts do and return a Job handle as soon as the server has accepted it, so you can submit work, do something else, and collect the result later. Each takes the same arguments as the method it mirrors, minus the ones that only mean something to a call that blocks — there is no num_partitions, because a partitioned call fans out across several jobs and has no single handle to give back, and no poll_interval or poll_timeout, which belong to Job.wait(). Use the blocking method when you want partitioning. Submission is retried only for failures that are known to precede acceptance (connection errors and HTTP 429); a read timeout or gateway error is not retried, because the server may already have created the job.

source

NixtlaClient.submit_forecast_job

NixtlaClient.submit_forecast_job (
    df, h, freq=None, id_col="unique_id", time_col="ds",
    target_col="y", X_df=None, level=None, quantiles=None,
    finetune_steps=0, finetune_depth=1, finetune_loss="default",
    finetuned_model_id=None, clean_ex_first=True, hist_exog_list=None,
    categorical_exog_list=None, validate_api_key=False,
    date_features=False, date_features_to_one_hot=False,
    model="timegpt-2.1", feature_contributions=False,
    model_parameters=None, multivariate=False, job_timeout_seconds=None
)

Submit a forecasting job and return a handle to it without waiting. Arguments are those of NixtlaClient.forecast, except that add_history and num_partitions are not supported.

	Type	Default	Details
job_timeout_seconds	int	None	Maximum time in seconds the server may spend on the job. It may not exceed the limit of the deployment. Defaults to the deployment’s limit.
Returns	Job		Handle to the submitted job. `job.wait()` returns the forecast as a pandas or polars DataFrame.

source

NixtlaClient.submit_cross_validation_job

NixtlaClient.submit_cross_validation_job (
    df, h, freq=None, id_col="unique_id", time_col="ds",
    target_col="y", level=None, quantiles=None, validate_api_key=False,
    n_windows=1, step_size=None, finetune_steps=0, finetune_depth=1,
    finetune_loss="default", finetuned_model_id=None, refit=True,
    clean_ex_first=True, hist_exog_list=None, date_features=False,
    date_features_to_one_hot=False, model="timegpt-2.1",
    model_parameters=None, multivariate=False,
    categorical_exog_list=None, job_timeout_seconds=None
)

Submit a cross-validation job and return a handle to it without waiting. Arguments are those of NixtlaClient.cross_validation, except that num_partitions is not supported.

	Type	Default	Details
job_timeout_seconds	int	None	Maximum time in seconds the server may spend on the job. It may not exceed the limit of the deployment. Defaults to the deployment’s limit.
Returns	Job		Handle to the submitted job. `job.wait()` returns the cross-validation results as a pandas or polars DataFrame.

source

NixtlaClient.submit_anomaly_detection_job

NixtlaClient.submit_anomaly_detection_job (
    df, h, detection_size, threshold_method="univariate", freq=None,
    id_col="unique_id", time_col="ds", target_col="y", level=99,
    clean_ex_first=True, step_size=None, finetune_steps=0,
    finetune_depth=1, finetune_loss="default", finetuned_model_id=None,
    hist_exog_list=None, date_features=False,
    date_features_to_one_hot=False, model="timegpt-2.1",
    model_parameters=None, refit=False, multivariate=False,
    job_timeout_seconds=None
)

Submit an online anomaly-detection job and return a handle to it without waiting. Arguments are those of NixtlaClient.detect_anomalies_online, except that num_partitions is not supported.

	Type	Default	Details
job_timeout_seconds	int	None	Maximum time in seconds the server may spend on the job. It may not exceed the limit of the deployment. Defaults to the deployment’s limit.
Returns	Job		Handle to the submitted job. `job.wait()` returns the anomalies as a pandas or polars DataFrame.

source

NixtlaClient.submit_finetune_job

NixtlaClient.submit_finetune_job (
    df, freq=None, id_col="unique_id", time_col="ds", target_col="y",
    finetune_steps=10, finetune_depth=1, finetune_loss="default",
    output_model_id=None, finetuned_model_id=None, model="timegpt-2.1",
    job_timeout_seconds=None
)

Submit a fine-tuning job and return a handle to it without waiting. Arguments are those of NixtlaClient.finetune.

	Type	Default	Details
job_timeout_seconds	int	None	Maximum time in seconds the server may spend on the job. It may not exceed the limit of the deployment. Defaults to the deployment’s limit.
Returns	Job		Handle to the submitted job. `job.wait()` returns the fine-tuned model id as a string.

source

NixtlaClient.submit_simulate_job

NixtlaClient.submit_simulate_job (
    df, h, freq=None, id_col="unique_id", time_col="ds",
    target_col="y", X_df=None, n_paths=100, quantiles=None, seed=None,
    finetuned_model_id=None, clean_ex_first=True, hist_exog_list=None,
    categorical_exog_list=None, validate_api_key=False,
    date_features=False, date_features_to_one_hot=False,
    model="timegpt-2.1", multivariate=False, job_timeout_seconds=None
)

Submit a simulation job and return a handle to it without waiting. Arguments are those of NixtlaClient.simulate, except that num_partitions is not supported — use simulate() to partition a large request.

	Type	Default	Details
job_timeout_seconds	int	None	Maximum time in seconds the server may spend on the job. It may not exceed the limit of the deployment. Defaults to the deployment’s limit.
Returns	Job		Handle to the submitted job. `job.wait()` returns the sample paths as a pandas or polars DataFrame.

source

NixtlaClient.submit_explain_job

NixtlaClient.submit_explain_job (
    df, method="granger", features=None, freq=None,
    id_col="unique_id", time_col="ds", target_col="y",
    categorical_exog_list=None, validate_api_key=False,
    job_timeout_seconds=None
)

Submit a feature-importance job and return a handle to it without waiting. Arguments are those of NixtlaClient.explain.

	Type	Default	Details
job_timeout_seconds	int	None	Maximum time in seconds the server may spend on the job. It may not exceed the limit of the deployment. Defaults to the deployment’s limit.
Returns	Job		Handle to the submitted job. `job.wait()` returns the weights as a pandas or polars DataFrame.

source

NixtlaClient.submit_execute_step_job

NixtlaClient.submit_execute_step_job (
    func_name, params, data=None, job_timeout_seconds=None
)

Run one TSMP top-level API call server-side and return a handle to it without waiting.

	Type	Default	Details
func_name	str		Name of the TSMP top-level API call to run.
params	dict		Arguments for the call. Reference a table from `data` with `nixtla.ref(key)`.
data	dict	None	Tables the call reads, keyed by the name `nixtla.ref` refers to. One step’s result `data` can be passed straight in here, so calls chain without any file or byte handling.
job_timeout_seconds	int	None	Maximum time in seconds the server may spend on the job. It may not exceed the limit of the deployment. Defaults to the deployment’s limit.
Returns	Job		Handle to the submitted job. `job.wait()` returns a `StepResult`.

Unlike the other tasks, this job’s result is binary and is served from its own endpoint rather than inlined into the status response. job.wait() therefore polls twice — once for the status, then for the payload — so a wait can take up to twice poll_timeout.

source

Job

Handle to a server-side asynchronous job. Returned by every submit_*_job method; not constructed directly. Importable from the package root as nixtla.Job.

	Type	Details
job_id	str	Identifier of the job on the server.
task	str	Task the job runs, e.g. `"forecast"` or `"simulate"`. Labels the errors the job raises.
result	Any	The result, once `wait()` has returned it; `None` before that.
status	JobStatus	Current status. Queries the server unless a terminal status is already known, since a finished job’s status cannot change again.

Job.wait

Job.wait (poll_interval=None, poll_timeout=3600.0, cancel_on_timeout=True)

Poll the job until it reaches a terminal state and return its result.

	Type	Default	Details
poll_interval	float	None	Seconds between two status checks, held fixed. Must be finite and non-negative. By default the client polls on an adaptive cadence instead: the first check comes after half a second and the interval doubles up to one check every 15 seconds.
poll_timeout	float	3600.0	Maximum seconds to wait for a terminal state before raising `AsyncJobTimeoutError`. Must be finite and positive, or `None` to poll until the server reports a terminal status.
cancel_on_timeout	bool	True	Whether to request cancellation when `poll_timeout` elapses, so a job you have given up on stops consuming server-side compute. Set to `False` to poll in short increments and call `wait()` again to resume.
Returns	Any		A DataFrame for forecast, cross-validation, anomaly-detection, simulate and explain jobs; a fine-tuned model id for finetune jobs; a `StepResult` for execute_step jobs.

Raises AsyncJobError if the job fails server-side, AsyncJobCancelledError if it reaches the cancelled state, and AsyncJobTimeoutError if poll_timeout elapses first. poll_timeout bounds the client’s polling only: with cancel_on_timeout=False the job keeps running server-side until its own deadline. A run of transient status-check failures does not end the wait — the client keeps polling while there is time left, and reports the last such failure as the cause if the wait times out.

Job.cancel

Job.cancel ()

Request cancellation of the job.

Job as a context manager

If an exception propagates out of the with block while the job is still running, cancellation is requested automatically as best-effort cleanup. A block left without an exception cancels nothing, and neither does an exception raised by a job that has already reached a terminal state. An error raised by a different job settles nothing about this one, so it is cleaned up as normal.

with client.submit_forecast_job(df=df, h=12, freq="D") as job:
    fcst = job.wait()

JobStatus

Status of a server-side job. PENDING, RUNNING, SUCCEEDED, FAILED and CANCELLED. Each compares equal to its lowercase string, so job.status == "succeeded" works. SUCCEEDED, FAILED and CANCELLED are terminal.

INTRODUCTION

SETUP

DATA REQUIREMENTS

FORECASTING

ANOMALY DETECTION

USE CASES

REFERENCE

About

SDK Reference

NixtlaClient

NixtlaClient.validate_api_key

NixtlaClient.forecast

NixtlaClient.simulate

NixtlaClient.explain

NixtlaClient.cross_validation

NixtlaClient.detect_anomalies

NixtlaClient.usage

NixtlaClient.list_models

NixtlaClient.finetune

NixtlaClient.finetuned_models

NixtlaClient.finetuned_model

NixtlaClient.delete_finetuned_model

NixtlaClient.plot

Asynchronous jobs

NixtlaClient.submit_forecast_job

NixtlaClient.submit_cross_validation_job

NixtlaClient.submit_anomaly_detection_job

NixtlaClient.submit_finetune_job

NixtlaClient.submit_simulate_job

NixtlaClient.submit_explain_job

NixtlaClient.submit_execute_step_job

Job

Job.wait

Job.cancel

Job as a context manager

JobStatus

​NixtlaClient

​NixtlaClient.validate_api_key

​NixtlaClient.forecast

​NixtlaClient.simulate

​NixtlaClient.explain

​NixtlaClient.cross_validation

​NixtlaClient.detect_anomalies

​NixtlaClient.usage

​NixtlaClient.list_models

​NixtlaClient.finetune

​NixtlaClient.finetuned_models

​NixtlaClient.finetuned_model

​NixtlaClient.delete_finetuned_model

​NixtlaClient.plot

​Asynchronous jobs

​NixtlaClient.submit_forecast_job

​NixtlaClient.submit_cross_validation_job

​NixtlaClient.submit_anomaly_detection_job

​NixtlaClient.submit_finetune_job

​NixtlaClient.submit_simulate_job

​NixtlaClient.submit_explain_job

​NixtlaClient.submit_execute_step_job

​Job

​Job.wait

​Job.cancel

​Job as a context manager

​JobStatus

NixtlaClient

NixtlaClient.validate_api_key

NixtlaClient.forecast

NixtlaClient.simulate

NixtlaClient.explain

NixtlaClient.cross_validation

NixtlaClient.detect_anomalies

NixtlaClient.usage

NixtlaClient.list_models

NixtlaClient.finetune

NixtlaClient.finetuned_models

NixtlaClient.finetuned_model

NixtlaClient.delete_finetuned_model

NixtlaClient.plot

Asynchronous jobs

NixtlaClient.submit_forecast_job

NixtlaClient.submit_cross_validation_job

NixtlaClient.submit_anomaly_detection_job

NixtlaClient.submit_finetune_job

NixtlaClient.submit_simulate_job

NixtlaClient.submit_explain_job

NixtlaClient.submit_execute_step_job

Job

Job.wait

Job.cancel

Job as a context manager

JobStatus