Forecast a time series
forecastSubmit numeric observations to forecast future sampling steps. Spends credits on successful calls. Choose and retain idempotency_key before submitting; no automatic retries, replay depends on server retention. Minimal example: {mode: route, series: [{values: [10,12,11], freq: D}], horizon: 2, quantiles: [0.1,0.5,0.9]}. Returns forecasts and meta as before, plus artifact by default for describe_forecast/plot_forecast. Save the embedded JSON attachment: it includes full input history and local context; no hosted storage is created. Context never becomes a model input. Billing is at meta.billing in millicredit strings (100 mc = 0.1 credits). Missing future inputs mean not supplied, not no events. Quantile bands do not establish coverage, cumulative intervals or peak probabilities. After uncertain completion, reuse the same key and API request; an expired key may cause a new charge.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"mode": "<mode>",
"series": "<series>"
},
"name": "forecast"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | "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 | No | Required when mode is "explicit". Must be a name returned by list_models. | |
| top_k | No | Ensemble only: cap on how many models participate. | |
| series | Yes | One to 64 series forecast in one request. All share horizon and quantiles. | |
| combine | No | Ensemble only. "mixture" averages the predictive distributions (default); "vincentize" averages the quantiles. | |
| context | No | 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. | |
| horizon | No | 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 | No | 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 | No | 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 | No | 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 | No | 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | ||
| artifact | No | Portable ephemeris.forecast v1 JSON including full history and local context. Save client-side and pass the object to describe_forecast/plot_forecast. Not a hosted URL. | |
| forecasts | No | One entry per input series, aligned with the request. | |
| artifact_error | No | ||
| artifact_status | No | included or unavailable. A packaging/size failure never discards the paid forecasts/meta response. |