API Reference
Perform forecasts with foundation models over a timeseries family.
Run a forecast query
Perform forecasts with foundation models. The input series may first be aggregated across dimensions and hierarchies.
query Parameters
modelThe forecasting model to use, such as t0-alpha.
Run a forecast query › Request Body
A forecast request: your data and what its columns mean (input), which columns to forecast (targets), which series and at what level of aggregation (selector), and when and how far ahead to forecast (cutoff, prediction_length and the other time settings).
A timeseries family written out in full: where its rows come from, plus what its columns mean.
targetsThe columns to forecast. Omit to forecast every column the schema
declares with the "target" kind.
Which series to forecast, and at what level of aggregation. Omit it
to forecast every series at the finest level the data has; {}
forecasts a single series, the total over everything. Cannot be
combined with selectors.
Several selectors, to forecast more than one level of aggregation in
one request, such as per store and per city. The response holds the
series of every selector. No two selectors may name the same levels.
Cannot be combined with selector.
{}Quantile levels to forecast for every target, as numbers in
[0, 1]; include "mean" to also request the mean. Defaults to
[0.1, 0.5, 0.9, "mean"].
Score the forecast against the actuals the request carries, and
report the scores under metrics in the response. A cutoff is
scored when its forecast window lies inside the data and observes
some target; missing actuals are skipped. The point scores use the
0.5 quantile when quantiles includes it, and the mean otherwise;
when this is set the mean is forecasted whether or not quantiles
asks for it.
true scores with the default settings and false does not score.
An object scores with the settings it gives: crps picks how the
CRPS weighs the quantile levels, "trapezoid" (the default) or
"mean_quantile_loss". The response does not say which was used.
return_actualsReturn each target's actuals over every forecast window under
actuals in the response, aligned with the forecast values. These
are the values the model reads, after aggregation and gap filling;
a step without a value is null.
model_configOptions for the model named by the model query parameter, passed to
it as given. Each model defines which options it takes and rejects
the ones it does not know.
A non-empty array of information cutoffs. For example ["latest"], an
explicit date ["2025-01-31"], or a recurring schedule [{ "every": "3d" }].
["latest"]Time to skip between the cutoff and the first forecast value. Defaults to
0: the forecast starts at the step right after the cutoff. With daily data
and a cutoff on Monday, a lead_time of "2d" starts the forecast on
Thursday.
How much history before each cutoff the model sees, such as "90d". Leave
it out to send all the history before the cutoff.
How far ahead to forecast, such as "28d" or 28 steps. Defaults to 1:
one step of the time grid.
Time each forecast value covers. Only one step of the time grid is
supported, the default 1. To forecast weekly or monthly totals, select a
coarser time level instead: "selector": { "weekly": "any" }.
Temporary clockwork covariates over the resolved cutoff/context window. UTC and positional calendar values, including pandas W/M/Q anchors. Omit or use [] to bypass. Unsupported on /v0; no publication-vintage guarantees.
[]Run a forecast query › Responses
The forecast, in the format the Accept header asks for:
application/json(the default): the whole forecast as one long-format table, in columnar form.application/x-ndjson: one series forecast per line, each sent as soon as it is ready.application/vnd.msgpack: the same series forecasts as MessagePack maps, back to back.application/vnd.apache.parquet: the long-format table as one Parquet file.
The two streamed formats send one record per series and cutoff, in no particular order. If a failure cuts a stream short, its last record is {"error": …}, a problem document.
The Parquet file has one row per series, cutoff and step, in the same order as the JSON table. Its columns:
time,cutoff: UTC timestamps.lead_time,span: ISO 8601 durations, as strings.identifiers: one field per identifier column, null on rows aggregated above it. Left out when the data has no identifier column.targets: one field per target, each holdingquantiles(one value per requested level, named by its label, such as"0.5"),mean(when requested, or whencompute_metricsis set),actual(whenreturn_actualsis set; null where the target has no actual) andwindow_metrics(whencompute_metricsis set:crps,scaled_crps,mae,mape,wapeandscaled_biasfor the row's whole forecast window, repeated on each of its rows; null where the window was not scored).
The forecast as a long-format table in columnar form: every field is a
column, and row i of the table is entry i of each column. There is one
row per series, cutoff and forecast step.
Accuracy metrics, one entry per series and cutoff whose forecast window
lies inside the actuals and observes some target. Present only when the
request set compute_metrics.