API documentation

Forecasting

Create forecasts from time-series data. Explore request fields and understand the response.

Create a forecast

Submits one or more time series and returns point forecasts for the requested horizon.

POST /v1/forecast

Request body

Field	Type	Description
model	string	Model ID to use. See GET /v1/models for available models.
series	object[]	Target series (64 max per request). Each series needs 16–2048 finite numeric values (NaN / Infinity / null are rejected).
series[].name	string \| null	Optional series name, echoed back in the response. Not filled in by the server when omitted.
series[].timestamps	string[] \| null	Optional ISO 8601 timestamps, one per value, strictly increasing. Uneven spacing is forecast as is (see Irregular time series below). Evenly spaced timestamps are accepted too; the actual spacing can be passed to the model as physical time, so adding them may change the result slightly (accuracy is equivalent).
series[].group	string \| null	Series sharing this value are forecast jointly as one multivariate task (omit for independent forecasts)
series[].role	string	target (default) or known_covariate; known_covariate is used as context only and is not returned
horizon	integer	Number of future points to forecast (1–512).
frequency	string \| null	Optional frequency hint (e.g. "1h"). Validated but not used by the model.
quantiles	number[] \| null	Optional quantile levels to return, chosen from 0.1, 0.2, … 0.9 (no duplicates). The response then includes quantiles as {"0.1": [...], ...} for the requested levels only; values equals the 0.5 quantile. Other levels, or models without quantile support, are rejected with 400 invalid_request. Quantiles do not add to output_points.

curl

curl -X POST https://YOUR_API_BASE/v1/forecast \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "yoft",
  "series": [
    {
      "name": "target",
      "values": [
        1,
        1.2,
        1.1,
        1.4,
        1.3,
        1.5,
        1.4,
        1.6,
        1.5,
        1.7,
        1.6,
        1.8,
        1.7,
        1.9,
        1.8,
        2
      ]
    }
  ],
  "horizon": 24
}'

Python (stdlib)

import json
import urllib.request

body = {
    "model": "yoft",
    "series": [
        {
            "name": "target",
            "values": [
                1,
                1.2,
                1.1,
                1.4,
                1.3,
                1.5,
                1.4,
                1.6,
                1.5,
                1.7,
                1.6,
                1.8,
                1.7,
                1.9,
                1.8,
                2
            ]
        }
    ],
    "horizon": 24
}

req = urllib.request.Request(
    "https://YOUR_API_BASE/v1/forecast",
    data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(req) as res:
    result = json.load(res)

print(result["forecast"][0]["values"])

Response

Returns per-series forecast values along with usage counts. request_id is shared with usage logs and error responses.

200 response

{
  "request_id": "req_a1b2c3d4e5f67890a1b2c3d4e5f67890",
  "model": "yoft",
  "model_version": "v1",
  "forecast": [
    {
      "name": "target",
      "values": [
        2.1,
        2.2
      ],
      "quantiles": null
    }
  ],
  "usage": {
    "input_points": 16,
    "output_points": 2,
    "series_count": 1
  }
}

Multivariate (joint forecasting)

Series that share a group are forecast together as one multivariate task. Without a group, each series is forecast independently.

A series with role known_covariate is used only as context; it is not returned in the forecast (only targets are).

Irregular time series (forecast as-is)

Attach timestamps to forecast series whose observations are not evenly spaced — no interpolation or resampling needed.

curl

curl -X POST https://YOUR_API_BASE/v1/forecast \
  -H "Authorization: Bearer $YOFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "yoft",
    "horizon": 3,
    "series": [{
      "values": [1.0, 1.2, 1.1, 1.4, 1.3, 1.5, 1.4, 1.6, 1.5, 1.7, 1.6, 1.8, 1.7, 1.9, 1.8, 2.0],
      "timestamps": ["2026-01-01T00:00:00Z", "2026-01-01T01:00:00Z", "2026-01-01T02:00:00Z",
                     "2026-01-01T05:00:00Z", "2026-01-01T06:00:00Z", "2026-01-01T07:00:00Z",
                     "2026-01-01T08:00:00Z", "2026-01-01T09:00:00Z", "2026-01-01T12:00:00Z",
                     "2026-01-01T13:00:00Z", "2026-01-01T14:00:00Z", "2026-01-01T15:00:00Z",
                     "2026-01-01T16:00:00Z", "2026-01-01T17:00:00Z", "2026-01-01T18:00:00Z",
                     "2026-01-01T19:00:00Z"]
    }]
  }'

Uneven gaps are never treated as evenly spaced and no interpolation is applied. Timestamps must be ISO 8601, one per value and strictly increasing. A series whose gaps are too uneven to fit the model's internal grid is rejected with 400 invalid_request (the message explains the limit) and nothing is billed.