Sign in
async jobs

Submit an async simulate job

Changed on

Queues a simulate job and returns immediately with its job_id. The job runs in a sandbox; poll GET /v2/simulate/jobs/{job_id} for its state and result. Accepts the same body as the synchronous endpoint plus an optional job_options.

post/v2/simulate/async

Request

  • Base URL: https://api.nixtla.io
  • URL: https://api.nixtla.io/v2/simulate/async
  • Auth: HTTP bearer

Request body

freqstring required

The frequency of the data represented as a string. 'D' for daily, 'M' for monthly, 'H' for hourly, and 'W' for weekly frequencies are available.

hinteger required

The forecasting horizon. This represents the number of time steps into the future that the forecast should predict.

modelstring

Model to use as a string. Common options are (but not restricted to) timegpt-1 and timegpt-1-long-horizon. Full options vary by different users. Contact support@nixtla.io for more information. 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.

finetuned_model_idstring nullable

ID of previously finetuned model

clean_ex_firstboolean

A boolean flag that indicates whether the API should preprocess (clean) the exogenous signal before applying the large time model. If True, the exogenous signal is cleaned; if False, the exogenous variables are applied after the large time model.

multivariateboolean

When True, sample paths are coupled across series via a shared-template Schaake shuffle (path k reflects the same historical period for every series) — this applies to ALL models. Falls back to independent per-series paths when no NaN-free shared history window exists (see coupled in the response). Also enables the multivariate marginal forecast for models that support it (timegpt-2.1).

n_pathsinteger

Number of sample paths to generate per series.

quantilesnumber[] nullable

Marginal quantile grid in (0, 1), strictly increasing, length in [2, 200]. Defaults to the model's native grid (native-quantile losses) or a dense grid (point-loss/conformal).

seedinteger nullable

Random seed for reproducibility. When omitted, a fresh random seed is drawn, so repeated unseeded requests return different paths.

Response

Successful Response

job_idstring required

Identifier for the accepted job. Prefixed per task (e.g. fc- for forecast).

Example response

{
  "job_id": "fc-4f2a1c9e8b7d4a6f9c3e1b5d7a9f2c4e"
}

Changes