curl --request POST \
--url https://api.nixtla.io/v2/forecast/async \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"freq": "D",
"h": 2,
"series": {
"sizes": [
5,
3
],
"y": [
1,
2,
3,
4,
5,
10,
20,
30
]
}
}
'import requests
url = "https://api.nixtla.io/v2/forecast/async"
payload = {
"freq": "D",
"h": 2,
"series": {
"sizes": [5, 3],
"y": [1, 2, 3, 4, 5, 10, 20, 30]
}
}
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({freq: 'D', h: 2, series: {sizes: [5, 3], y: [1, 2, 3, 4, 5, 10, 20, 30]}})
};
fetch('https://api.nixtla.io/v2/forecast/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/forecast/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([
'freq' => 'D',
'h' => 2,
'series' => [
'sizes' => [
5,
3
],
'y' => [
1,
2,
3,
4,
5,
10,
20,
30
]
]
]),
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/forecast/async"
payload := strings.NewReader("{\n \"freq\": \"D\",\n \"h\": 2,\n \"series\": {\n \"sizes\": [\n 5,\n 3\n ],\n \"y\": [\n 1,\n 2,\n 3,\n 4,\n 5,\n 10,\n 20,\n 30\n ]\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/forecast/async")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"freq\": \"D\",\n \"h\": 2,\n \"series\": {\n \"sizes\": [\n 5,\n 3\n ],\n \"y\": [\n 1,\n 2,\n 3,\n 4,\n 5,\n 10,\n 20,\n 30\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nixtla.io/v2/forecast/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 \"freq\": \"D\",\n \"h\": 2,\n \"series\": {\n \"sizes\": [\n 5,\n 3\n ],\n \"y\": [\n 1,\n 2,\n 3,\n 4,\n 5,\n 10,\n 20,\n 30\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"job_id": "fc-4f2a1c9e8b7d4a6f9c3e1b5d7a9f2c4e"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Submit an async forecast job
Queues a forecast job and returns immediately with its job_id. The job runs in a sandbox; poll GET /v2/forecast/jobs/{job_id} for its state and result. Accepts the same body as the synchronous endpoint plus an optional job_options.
curl --request POST \
--url https://api.nixtla.io/v2/forecast/async \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"freq": "D",
"h": 2,
"series": {
"sizes": [
5,
3
],
"y": [
1,
2,
3,
4,
5,
10,
20,
30
]
}
}
'import requests
url = "https://api.nixtla.io/v2/forecast/async"
payload = {
"freq": "D",
"h": 2,
"series": {
"sizes": [5, 3],
"y": [1, 2, 3, 4, 5, 10, 20, 30]
}
}
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({freq: 'D', h: 2, series: {sizes: [5, 3], y: [1, 2, 3, 4, 5, 10, 20, 30]}})
};
fetch('https://api.nixtla.io/v2/forecast/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/forecast/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([
'freq' => 'D',
'h' => 2,
'series' => [
'sizes' => [
5,
3
],
'y' => [
1,
2,
3,
4,
5,
10,
20,
30
]
]
]),
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/forecast/async"
payload := strings.NewReader("{\n \"freq\": \"D\",\n \"h\": 2,\n \"series\": {\n \"sizes\": [\n 5,\n 3\n ],\n \"y\": [\n 1,\n 2,\n 3,\n 4,\n 5,\n 10,\n 20,\n 30\n ]\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/forecast/async")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"freq\": \"D\",\n \"h\": 2,\n \"series\": {\n \"sizes\": [\n 5,\n 3\n ],\n \"y\": [\n 1,\n 2,\n 3,\n 4,\n 5,\n 10,\n 20,\n 30\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nixtla.io/v2/forecast/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 \"freq\": \"D\",\n \"h\": 2,\n \"series\": {\n \"sizes\": [\n 5,\n 3\n ],\n \"y\": [\n 1,\n 2,\n 3,\n 4,\n 5,\n 10,\n 20,\n 30\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"job_id": "fc-4f2a1c9e8b7d4a6f9c3e1b5d7a9f2c4e"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Body
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.
A list of values representing the prediction intervals. Each value is a percentage that indicates the level of certainty for the corresponding prediction interval. For example, [80, 90] defines 80% and 90% prediction intervals.
10 <= x < 100The loss used to train the large time model on the data. Select from ['default', 'mae', 'mse', 'rmse', 'mape', 'smape', 'poisson']. It will only be used if finetune_steps is larger than 0. Default is a robust loss function that is less sensitive to outliers.
default, mae, mse, rmse, mape, smape, poisson 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. Note that this parameter is only effective for timegpt-1 and timegpt-1-long-horizon models; it has no effect on the other models. By default, the value is set to 1.
1, 2, 3, 4, 5 Method used to compute feature contributions. Options are: 'shapley' (default), 'intervention', 'granger', 'transfer_entropy'. The methods differ in semantics: 'shapley' returns per-timestep contributions that sum to the forecast (last row = per-timestep base prediction); 'intervention' returns each feature's counterfactual effect (forecast minus forecast with that feature held at its baseline) and does NOT sum to the forecast; 'granger'/'transfer_entropy' allocate each series' forecast deviation from its mean proportionally to model-agnostic historical importance weights — the rows sum to the forecast by construction, but they are a proportional allocation describing relationships in the data, not a per-feature attribution of this specific forecast. Use the /v2/explain endpoint for standalone historical importance weights.
shapley, intervention, granger, transfer_entropy Was this page helpful?