Input schema (JSON)
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"mode",
"series"
],
"properties": {
"mode": {
"enum": [
"route",
"ensemble",
"explicit"
],
"type": "string",
"description": "\"route\": automatically select a model. \"ensemble\": blend compatible models and may cost more. Neither guarantees accuracy or calibration. \"explicit\": run the single model named in `model`."
},
"model": {
"type": "string",
"minLength": 1,
"description": "Required when mode is \"explicit\". Must be a name returned by list_models."
},
"top_k": {
"type": "integer",
"maximum": 16,
"minimum": 1,
"description": "Ensemble only: cap on how many models participate."
},
"series": {
"type": "array",
"items": {
"type": "object",
"required": [
"values"
],
"properties": {
"freq": {
"type": "string",
"minLength": 1,
"description": "Pandas-style sampling frequency such as \"H\", \"D\", \"W\", \"15min\" or \"M\". Improves routing and seasonal handling; omit if unknown."
},
"values": {
"anyOf": [
{
"type": "array",
"items": {
"type": "number"
},
"minItems": 1
},
{
"type": "array",
"items": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 1
},
"minItems": 1
}
],
"description": "Observed history, oldest first. A flat number array is one univariate series. A nested array is one multivariate series with one inner array per variate, all the same length."
},
"covariates": {
"type": "object",
"required": [
"past"
],
"properties": {
"past": {
"type": "object",
"description": "Named historical channels, each the same length as the series context.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "number"
}
}
},
"future": {
"type": "object",
"description": "Future numeric channels (known future or explicit scenario assumptions), each exactly `horizon` long. Every future channel must also appear in `past`.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "number"
}
}
}
},
"description": "Optional exogenous covariates. Only models with `covariates: true` in list_models can use them. In route and ensemble mode the panel narrows to those models; in explicit mode, naming a model without covariate support is an error."
}
}
},
"maxItems": 64,
"minItems": 1,
"description": "One to 64 series forecast in one request. All share horizon and quantiles."
},
"combine": {
"enum": [
"mixture",
"vincentize"
],
"type": "string",
"description": "Ensemble only. \"mixture\" averages the predictive distributions (default); \"vincentize\" averages the quantiles."
},
"context": {
"type": "object",
"required": [
"series"
],
"properties": {
"series": {
"type": "array",
"items": {
"type": "object",
"properties": {
"unit": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
},
"timezone": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
},
"series_id": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
},
"timestamps": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 100
}
},
{
"type": "null"
}
]
},
"measurement": {
"anyOf": [
{
"enum": [
"period_total",
"period_average",
"point_in_time"
],
"type": "string"
},
{
"type": "null"
}
]
},
"recorded_as_of": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
},
"future_timestamps": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 100
}
},
{
"type": "null"
}
]
},
"target_description": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
},
"source_available_at": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
},
"future_covariate_roles": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"enum": [
"known_future",
"scenario_assumption",
"unspecified"
],
"type": "string"
}
}
},
"additionalProperties": false
},
"maxItems": 64
},
"scenario_assumptions": {
"type": "array",
"items": {
"type": "string",
"maxLength": 2000
},
"maxItems": 100
}
},
"description": "Local artifact metadata, never sent as model inputs. series aligns with input series; timestamps align with history and future_timestamps with horizon. Units/target/measurement/timezone must come from the user; unknowns stay null. Future-input labels are caller assertions; narrative assumptions do not change inference.",
"additionalProperties": false
},
"horizon": {
"type": "integer",
"maximum": 4096,
"minimum": 1,
"description": "Number of future steps to forecast, 1 to 4096. Defaults to 64. Some models stop short of this (max_horizon in list_models): route and ensemble skip them, explicit mode rejects the request."
},
"quantiles": {
"type": "array",
"items": {
"type": "number",
"exclusiveMaximum": 1,
"exclusiveMinimum": 0
},
"maxItems": 21,
"description": "Up to 21 quantile levels strictly between 0 and 1, for example [0.1, 0.5, 0.9]. The response keys forecasts by these as decimal strings."
},
"context_len": {
"type": "integer",
"maximum": 16384,
"minimum": 1,
"description": "Most recent points per variate to feed the model (history length does not affect pricing), 1 to 16384. Defaults to 256. Values beyond the model's context cap are truncated at the cap."
},
"idempotency_key": {
"type": "string",
"pattern": "^[A-Za-z0-9._:-]{8,128}$",
"description": "Client-chosen key, 8 to 128 characters of letters, numbers, dot, underscore, colon or hyphen. A retry with the same key and identical API body replays while retained by the server. Retain the key before submission; expired keys may cause a new charge."
},
"include_artifact": {
"type": "boolean",
"description": "Default true: include a portable ephemeris.forecast v1 artifact and embedded JSON attachment (up to 1 MiB), with full input history. Save it client-side for describe_forecast/plot_forecast or the CLI. false returns the existing API response only. No persistent hosted storage is created."
}
}
}