Submit an async simulate job
curl --request POST \
--url https://api.nixtla.io/v2/simulate/async \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"series": {
"y": [
123
],
"sizes": [
123
],
"X_future": [
[
123
]
],
"X": [
[
123
]
],
"categorical_exog": [
1
],
"start_datetime": [
"<string>"
]
},
"freq": "<string>",
"h": 123,
"model": "timegpt-1",
"finetuned_model_id": "<string>",
"clean_ex_first": true,
"multivariate": false,
"n_paths": 100,
"quantiles": [
123
],
"seed": 4611686018427388000,
"job_options": {
"timeout_seconds": 1
}
}
'import requests
url = "https://api.nixtla.io/v2/simulate/async"
payload = {
"series": {
"y": [123],
"sizes": [123],
"X_future": [[123]],
"X": [[123]],
"categorical_exog": [1],
"start_datetime": ["<string>"]
},
"freq": "<string>",
"h": 123,
"model": "timegpt-1",
"finetuned_model_id": "<string>",
"clean_ex_first": True,
"multivariate": False,
"n_paths": 100,
"quantiles": [123],
"seed": 4611686018427388000,
"job_options": { "timeout_seconds": 1 }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
series: {
y: [123],
sizes: [123],
X_future: [[123]],
X: [[123]],
categorical_exog: [1],
start_datetime: ['<string>']
},
freq: '<string>',
h: 123,
model: 'timegpt-1',
finetuned_model_id: '<string>',
clean_ex_first: true,
multivariate: false,
n_paths: 100,
quantiles: [123],
seed: 4611686018427388000,
job_options: {timeout_seconds: 1}
})
};
fetch('https://api.nixtla.io/v2/simulate/async', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nixtla.io/v2/simulate/async",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'series' => [
'y' => [
123
],
'sizes' => [
123
],
'X_future' => [
[
123
]
],
'X' => [
[
123
]
],
'categorical_exog' => [
1
],
'start_datetime' => [
'<string>'
]
],
'freq' => '<string>',
'h' => 123,
'model' => 'timegpt-1',
'finetuned_model_id' => '<string>',
'clean_ex_first' => true,
'multivariate' => false,
'n_paths' => 100,
'quantiles' => [
123
],
'seed' => 4611686018427388000,
'job_options' => [
'timeout_seconds' => 1
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.nixtla.io/v2/simulate/async"
payload := strings.NewReader("{\n \"series\": {\n \"y\": [\n 123\n ],\n \"sizes\": [\n 123\n ],\n \"X_future\": [\n [\n 123\n ]\n ],\n \"X\": [\n [\n 123\n ]\n ],\n \"categorical_exog\": [\n 1\n ],\n \"start_datetime\": [\n \"<string>\"\n ]\n },\n \"freq\": \"<string>\",\n \"h\": 123,\n \"model\": \"timegpt-1\",\n \"finetuned_model_id\": \"<string>\",\n \"clean_ex_first\": true,\n \"multivariate\": false,\n \"n_paths\": 100,\n \"quantiles\": [\n 123\n ],\n \"seed\": 4611686018427388000,\n \"job_options\": {\n \"timeout_seconds\": 1\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.nixtla.io/v2/simulate/async")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"series\": {\n \"y\": [\n 123\n ],\n \"sizes\": [\n 123\n ],\n \"X_future\": [\n [\n 123\n ]\n ],\n \"X\": [\n [\n 123\n ]\n ],\n \"categorical_exog\": [\n 1\n ],\n \"start_datetime\": [\n \"<string>\"\n ]\n },\n \"freq\": \"<string>\",\n \"h\": 123,\n \"model\": \"timegpt-1\",\n \"finetuned_model_id\": \"<string>\",\n \"clean_ex_first\": true,\n \"multivariate\": false,\n \"n_paths\": 100,\n \"quantiles\": [\n 123\n ],\n \"seed\": 4611686018427388000,\n \"job_options\": {\n \"timeout_seconds\": 1\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nixtla.io/v2/simulate/async")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"series\": {\n \"y\": [\n 123\n ],\n \"sizes\": [\n 123\n ],\n \"X_future\": [\n [\n 123\n ]\n ],\n \"X\": [\n [\n 123\n ]\n ],\n \"categorical_exog\": [\n 1\n ],\n \"start_datetime\": [\n \"<string>\"\n ]\n },\n \"freq\": \"<string>\",\n \"h\": 123,\n \"model\": \"timegpt-1\",\n \"finetuned_model_id\": \"<string>\",\n \"clean_ex_first\": true,\n \"multivariate\": false,\n \"n_paths\": 100,\n \"quantiles\": [\n 123\n ],\n \"seed\": 4611686018427388000,\n \"job_options\": {\n \"timeout_seconds\": 1\n }\n}"
response = http.request(request)
puts response.read_body{
"job_id": "fc-4f2a1c9e8b7d4a6f9c3e1b5d7a9f2c4e"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}async jobs
Submit an async simulate job
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
Submit an async simulate job
curl --request POST \
--url https://api.nixtla.io/v2/simulate/async \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"series": {
"y": [
123
],
"sizes": [
123
],
"X_future": [
[
123
]
],
"X": [
[
123
]
],
"categorical_exog": [
1
],
"start_datetime": [
"<string>"
]
},
"freq": "<string>",
"h": 123,
"model": "timegpt-1",
"finetuned_model_id": "<string>",
"clean_ex_first": true,
"multivariate": false,
"n_paths": 100,
"quantiles": [
123
],
"seed": 4611686018427388000,
"job_options": {
"timeout_seconds": 1
}
}
'import requests
url = "https://api.nixtla.io/v2/simulate/async"
payload = {
"series": {
"y": [123],
"sizes": [123],
"X_future": [[123]],
"X": [[123]],
"categorical_exog": [1],
"start_datetime": ["<string>"]
},
"freq": "<string>",
"h": 123,
"model": "timegpt-1",
"finetuned_model_id": "<string>",
"clean_ex_first": True,
"multivariate": False,
"n_paths": 100,
"quantiles": [123],
"seed": 4611686018427388000,
"job_options": { "timeout_seconds": 1 }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
series: {
y: [123],
sizes: [123],
X_future: [[123]],
X: [[123]],
categorical_exog: [1],
start_datetime: ['<string>']
},
freq: '<string>',
h: 123,
model: 'timegpt-1',
finetuned_model_id: '<string>',
clean_ex_first: true,
multivariate: false,
n_paths: 100,
quantiles: [123],
seed: 4611686018427388000,
job_options: {timeout_seconds: 1}
})
};
fetch('https://api.nixtla.io/v2/simulate/async', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nixtla.io/v2/simulate/async",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'series' => [
'y' => [
123
],
'sizes' => [
123
],
'X_future' => [
[
123
]
],
'X' => [
[
123
]
],
'categorical_exog' => [
1
],
'start_datetime' => [
'<string>'
]
],
'freq' => '<string>',
'h' => 123,
'model' => 'timegpt-1',
'finetuned_model_id' => '<string>',
'clean_ex_first' => true,
'multivariate' => false,
'n_paths' => 100,
'quantiles' => [
123
],
'seed' => 4611686018427388000,
'job_options' => [
'timeout_seconds' => 1
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.nixtla.io/v2/simulate/async"
payload := strings.NewReader("{\n \"series\": {\n \"y\": [\n 123\n ],\n \"sizes\": [\n 123\n ],\n \"X_future\": [\n [\n 123\n ]\n ],\n \"X\": [\n [\n 123\n ]\n ],\n \"categorical_exog\": [\n 1\n ],\n \"start_datetime\": [\n \"<string>\"\n ]\n },\n \"freq\": \"<string>\",\n \"h\": 123,\n \"model\": \"timegpt-1\",\n \"finetuned_model_id\": \"<string>\",\n \"clean_ex_first\": true,\n \"multivariate\": false,\n \"n_paths\": 100,\n \"quantiles\": [\n 123\n ],\n \"seed\": 4611686018427388000,\n \"job_options\": {\n \"timeout_seconds\": 1\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.nixtla.io/v2/simulate/async")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"series\": {\n \"y\": [\n 123\n ],\n \"sizes\": [\n 123\n ],\n \"X_future\": [\n [\n 123\n ]\n ],\n \"X\": [\n [\n 123\n ]\n ],\n \"categorical_exog\": [\n 1\n ],\n \"start_datetime\": [\n \"<string>\"\n ]\n },\n \"freq\": \"<string>\",\n \"h\": 123,\n \"model\": \"timegpt-1\",\n \"finetuned_model_id\": \"<string>\",\n \"clean_ex_first\": true,\n \"multivariate\": false,\n \"n_paths\": 100,\n \"quantiles\": [\n 123\n ],\n \"seed\": 4611686018427388000,\n \"job_options\": {\n \"timeout_seconds\": 1\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nixtla.io/v2/simulate/async")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"series\": {\n \"y\": [\n 123\n ],\n \"sizes\": [\n 123\n ],\n \"X_future\": [\n [\n 123\n ]\n ],\n \"X\": [\n [\n 123\n ]\n ],\n \"categorical_exog\": [\n 1\n ],\n \"start_datetime\": [\n \"<string>\"\n ]\n },\n \"freq\": \"<string>\",\n \"h\": 123,\n \"model\": \"timegpt-1\",\n \"finetuned_model_id\": \"<string>\",\n \"clean_ex_first\": true,\n \"multivariate\": false,\n \"n_paths\": 100,\n \"quantiles\": [\n 123\n ],\n \"seed\": 4611686018427388000,\n \"job_options\": {\n \"timeout_seconds\": 1\n }\n}"
response = http.request(request)
puts response.read_body{
"job_id": "fc-4f2a1c9e8b7d4a6f9c3e1b5d7a9f2c4e"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Authorizations
HTTPBearer
Body
application/json
Show child attributes
Show child attributes
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.
The forecasting horizon. This represents the number of time steps into the future that the forecast should predict.
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.
ID of previously finetuned model
Pattern:
^[a-zA-Z0-9\-_]{1,36}$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.
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).
Number of sample paths to generate per series.
Required range:
1 <= x <= 10000Marginal 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).
Random seed for reproducibility. When omitted, a fresh random seed is drawn, so repeated unseeded requests return different paths.
Required range:
-9223372036854776000 <= x <= 18446744073709552000Show child attributes
Show child attributes
Response
Successful Response
The 202 every async submit returns. Shared by all tasks — they differ in request, not reply.
Identifier for the accepted job. Prefixed per task (e.g. fc- for forecast).
Example:
"fc-4f2a1c9e8b7d4a6f9c3e1b5d7a9f2c4e"
Was this page helpful?