Schemas

ForecastRequest

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).

Input · required

A timeseries family written out in full: where its rows come from, plus what its columns mean.

targets

array | null · minItems: 1

The columns to forecast. Omit to forecast every column the schema declares with the "target" kind.

Default: null

Selector

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.

Default: null

Selector[] · minItems: 1

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.

Default: null

object

Default: {}

array | null · minItems: 1 · unique

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"].

Default: null

MetricsRequest

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.

Default: false

return_actuals

boolean

Return 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.

Default: false

model_config

Options 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.

Default: null

Cutoff[] · minItems: 1

A non-empty array of information cutoffs. For example ["latest"], an explicit date ["2025-01-31"], or a recurring schedule [{ "every": "3d" }].

Default: ["latest"]

LeadTime

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.

Default: 0

Context

How much history before each cutoff the model sees, such as "90d". Leave it out to send all the history before the cutoff.

Default: null

PredictionLength

How far ahead to forecast, such as "28d" or 28 steps. Defaults to 1: one step of the time grid.

Default: 1

Span

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" }.

Default: 1

array · maxItems: 32

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.

Default: []

Input

A timeseries family written out in full: where its rows come from, plus what its columns mean.

Source · required

Where the timeseries family's rows come from.

object · required

The timeseries family's columns, keyed by name. Exactly one declares kind: "time".

has_gaps

boolean | null

Whether rows may be missing from the grid. false, the default, asserts the rows are complete and reports the first gap as an error. true completes the grid and lets series start late, then fills the rows it added the way each column says to: a column with an impute rule gets that rule's value, and a column without one is left null.

object | null

Roll-up paths, keyed by the name you give each one.

Covariate[]

Other timeseries families to attach, each contributing extra variables.

name

string | null

A name for the timeseries family, for your own reference.

description

string | null

What the timeseries family holds, for your own reference.

metadata

Anything you want to keep alongside the timeseries family. It is stored as written and plays no part in the forecast.

Column

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	No specific criteria
	No specific criteria

Properties for Role shorthand:

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = string
	type = string

Properties for Identifier:

Const value: identifier

Names which series a row belongs to, such as a store or a product.

ColumnRole

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = string
	type = string

Properties for Identifier:

Const value: identifier

Names which series a row belongs to, such as a store or a product.

ColumnDeclaration

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: kind
	type = object · requires: kind
	type = object · requires: kind
	type = object · requires: kind
	type = object · requires: kind
	type = object · requires: kind

Properties for Identifier column:

Names which series a row belongs to.

kind

string · const · required

Const value: identifier

type

Type

Type of the column's values. Omit it and the type is read from the data; a type given here wins.

Example 1: int64

Example 2: float64

Example 3: string

Example 4: date32

Example 5: timestamp_us

Example 6: nullable<float64>

column

string | null

Column to read in the source data, when it differs from the name this declaration sits under. Cannot be combined with virtual.

virtual

Expression

Expression computing the column instead of reading it from the source. Cannot be combined with column. Not supported yet: a request declaring it is rejected.

Example 1: sum

Example 2: mean

Example 3: max

Example 4: 0

description

string | null

What the column means, for your own reference.

Type

string

A value type: bool, int32, int64, float32, float64, string, date32, or timestamp_us. Wrap one in nullable<...> to allow missing values, or in list<...> for a column of lists.

Example 1: int64

Example 2: float64

Example 3: string

Example 4: date32

Example 5: timestamp_us

Example 6: nullable<float64>

Expression

string

An expression: an aggregation (sum, mean, avg, min, max, or first, any one value of a bucket whose values are all equal), a literal (0, 1.5, true), null (a NULL of the input's type), or a comma-separated tuple of those in parentheses.

Example 1: sum

Example 2: mean

Example 3: max

Example 4: 0

Known

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	No specific criteria
	type = object · requires: at

Properties for Named horizon:

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Historical:

Const value: historical

Observed up to the cutoff only.

KnownTime

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Historical:

Const value: historical

Observed up to the cutoff only.

KnownAt

An observation time given as an expression. Not supported yet: a request declaring it is rejected.

at

Expression · required

When the value becomes observable, as an expression over the time column.

Example 1: sum

Example 2: mean

Example 3: max

Example 4: 0

Impute

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: const
	type = object · requires: locf
	type = object · requires: locb
	type = object · requires: rolling

Properties for Constant:

Fill every gap with the same value.

const

number | boolean | string · required

The value to fill with. A string keeps its own quotation marks inside the JSON string, as the examples show, and there is no null: to leave gaps empty, omit the rule instead.

Example 1: 0

Example 2: 1.5

Example 3: true

Example 4: "n/a"

GapFill

How far a carried value reaches.

max_gap

integer | null · uint64 · min: 0 · max: 4294967295

Longest run of consecutive missing values to fill, counted in grid steps. Omit it to fill runs of any length.

Rolling

A statistic over the values around each gap.

RollingStat · required

Which statistic to compute.

size

integer · uint64 · min: 1 · max: 4294967295 · required

How many rows around the missing cell contribute. A centred window needs an even number, so it has as many rows on each side.

RollingAlignment

Where the window sits relative to the value being filled. Defaults to trailing. centered needs an even size.

RollingStat

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = string
	type = string

Properties for Mean:

Const value: mean

Arithmetic mean of the window.

RollingAlignment

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = string

Properties for Trailing:

Const value: trailing

The window covers the steps before it.

Interpolate

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	No specific criteria
	type = object · requires: proportional_by

Properties for Named method:

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Broadcast:

Const value: broadcast

Copy the coarser value onto every finer row.

InterpolateName

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Broadcast:

Const value: broadcast

Copy the coarser value onto every finer row.

ProportionalBy

A split weighted by another column.

proportional_by

string · required

Column whose values weight the split.

Rule

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: at, impute
	type = object · requires: from, to

Properties for Filling rule:

How to fill missing values at the levels it names.

ImputeRule

at

RankPattern · required

Levels this rule applies at.

Example 1: *

Example 2: region=*

Example 3: region=city

Example 4: region>=city

Example 5: region=absent

Impute · required

How the missing values are filled there.

ImputeRule

How to fill missing values at named levels.

at

RankPattern · required

Levels this rule applies at.

Example 1: *

Example 2: region=*

Example 3: region=city

Example 4: region>=city

Example 5: region=absent

Impute · required

How the missing values are filled there.

RankPattern

string

Which levels a rule applies to: * for every level of every roll-up path, or a comma-separated list of clauses, one per path. A clause compares a path's level with =, >=, <=, >, or <, where the coarser level is the greater one, and its right-hand side is a level name, * for any level, or absent for rows not broken down by that path at all.

Example 1: *

Example 2: region=*

Example 3: region=city

Example 4: region>=city

Example 5: region=absent

TransitionRule

How values move from one level to another: aggregate when the target is coarser, interpolate when it is finer. Giving neither leaves that change with no rule of its own.

from

RankPattern · required

Levels the values are read at.

Example 1: *

Example 2: region=*

Example 3: region=city

Example 4: region>=city

Example 5: region=absent

to

RankPattern · required

Levels the values are produced at.

Example 1: *

Example 2: region=*

Example 3: region=city

Example 4: region>=city

Example 5: region=absent

aggregate

Expression

How the values combine, when to is the coarser side.

Example 1: sum

Example 2: mean

Example 3: max

Example 4: 0

PartialBuckets

Whether this aggregation includes partial leading and trailing time buckets. Defaults to drop. An allowed bucket is an ordinary input to later aggregations. Requires aggregate on this rule; rejected cells are not imputed.

Interpolate

How the values are spread out, when to is the finer side.

PartialBuckets

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Variant 1:

Const value: drop

Require full bucket coverage at this aggregation's input grain (the default).

Encoding

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	No specific criteria
	No specific criteria

Properties for Named encoding:

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string

Properties for Ordinal:

Const value: ordinal

Numbers the distinct values 0, 1, 2, … in the order they first appear in time across the whole data, ties broken by value. A code depends only on values that appeared no later than its own, so a category first seen after a cutoff never shifts the codes seen before it. Missing values are one more category, numbered the same way.

EncodingName

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string

Properties for Ordinal:

Const value: ordinal

ConfiguredEncoding

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: ordinal

Properties for Ordinal:

Numbers the distinct values 0, 1, 2, … in the order they first appear in time across the whole data, ties broken by value.

Ordinal · required

Options of the ordinal encoding.

Ordinal

Options of the ordinal encoding.

OrdinalNulls

What becomes of missing values. Defaults to coded.

OrdinalNulls

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Missing:

Const value: missing

Missing values stay missing.

Interval

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = object

Properties for Interval string:

IntervalString

The spacing written as one string.

Example 1: daily

Example 2: weekly

Example 3: monthly

Example 4: 1d

Example 5: 5min

Example 6: 1d 3h

Example 7: P1Y2M10D

IntervalString

string

An interval written as one string: a name (daily, weekly, 5min), numbers with units separated by spaces (1d 3h), or an ISO 8601 duration in capitals (P1Y2M10D). Names accept the singular, the plural, and the adjective (day, days, daily), in any case. The units are y, q, mo, w, d, h, m, s and us; write them lowercase, since m is minutes and mo months.

Example 1: daily

Example 2: weekly

Example 3: monthly

Example 4: 1d

Example 5: 5min

Example 6: 1d 3h

Example 7: P1Y2M10D

IntervalParts

An interval written field by field. Fields left out count as zero, and the total has to be strictly forward.

years

integer | null · int64

Whole years.

months

integer | null · int64

Whole months.

days

integer | null · int64

Whole days.

hours

integer | null · int64

Whole hours.

minutes

integer | null · int64

Whole minutes.

seconds

integer | null · int64

Whole seconds.

ms

integer | null · int64

Whole milliseconds.

us

integer | null · int64

Whole microseconds.

Anchor

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = object

Properties for Weekday, month, or instant:

string

A weekday, which anchors weekly grids; a month, which anchors yearly ones; or the date or timestamp the grid starts at.

Example 1: monday

Example 2: april

Example 3: 2024-01-06

Example 4: 2024-01-06T00:00:00Z

Partition

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = object

Properties for Spacing:

IntervalString

The grid's spacing on its own.

Example 1: daily

Example 2: weekly

Example 3: monthly

Example 4: 1d

Example 5: 5min

Example 6: 1d 3h

Example 7: P1Y2M10D

PartitionBody

A coarser grid with its own spacing and start.

Interval

Spacing of this grid. Omit it and the name this entry sits under names the spacing, so {} is enough under a key like weekly.

Anchor

Where this grid's buckets start. Omit it for the usual start for the spacing.

Chain

string[] · minItems: 1

One roll-up path: identifier columns from finest to coarsest. At least one column.

Example: {"0": "store", "1": "city", "2": "country"}{"0": "store", "1": "city", "2": "country"}

Source

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: inline
	type = object · requires: uri
	type = object · requires: parquet

Properties for Inline rows:

The rows themselves, one array of values per column name. Every array has the same length, and each position across them is one row.

object · required

The rows themselves, one array of values per column name. Every array has the same length, and each position across them is one row.

Example 1:

{
  "time": ["2020-01-01", "2020-01-02", "2020-01-03"],
  "sales": [12, 9, 15]
}{
  "time": ["2020-01-01", "2020-01-02", "2020-01-03"],
  "sales": [12, 9, 15]
}

Example 2:

{
  "time": ["2020-01-01", "2020-01-01", "2020-01-02", "2020-01-02"],
  "store": ["north", "south", "north", "south"],
  "sales": [12, 7, 9, 11],
  "on_promotion": [false, false, true, false]
}{
  "time": ["2020-01-01", "2020-01-01", "2020-01-02", "2020-01-02"],
  "store": ["north", "south", "north", "south"],
  "sales": [12, 7, 9, 11],
  "on_promotion": [false, false, true, false]
}

Scalar

number | boolean | string | null

A single value: a number, a boolean, a string, or null for a missing observation.

Example 1: 12

Example 2: 1.5

Example 3: north

Example 4: true

Example 5: null

ParquetPaths

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = array

Properties for One path:

string

One file, or a glob matching several.

Example 1: sales.parquet

Example 2: sales/*.parquet

Covariate

Another table attached to this one, contributing extra variables such as weather or prices. The attached table only adds columns: its rows are matched onto this table's rows by on, and this table's series and time steps stay as they are. One exception: when a kept variable is of kind future and on matches the time column, each series also takes the attached rows it matches past its last time step, with its own variables empty there. A series read at a finer time step than the one on matches is not extended.

A kept variable keeps its column name unless rename gives it another. When it clashes with a column already present, the request is rejected if only or rename is given; otherwise the attached column is renamed with an _rhs suffix (temperature becomes temperature_rhs).

VersionedSchema · required

The attached timeseries family, written out here or pointed at elsewhere.

array | null

Which columns to match rows on. Required. An empty list matches every attached row to every row of this table, for a covariate shared by all series, such as a national price index.

Example 1: {"0": "time"}{"0": "time"}

Example 2: {"0": {"base": "store", "attached": "shop_id"}, "1": "time"}{"0": {"base": "store", "attached": "shop_id"}, "1": "time"}

Example 3: {"0": {"base": "region", "attached": "region"}, "1": "time"}{"0": {"base": "region", "attached": "region"}, "1": "time"}

only

array | null

Which of the attached table's variables to keep, by their name there. Omit it to keep all of them.

object | null

Names to give the kept variables, keyed by the name they carry on the attached timeseries family.

VersionedSchema

A schema document: one timeseries family, plus the version saying which schema format it is written in.

version

string · enum · required

Which schema format this document is written in.

Enum values:

0.1

0.2

0.3

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: columns, source, version
	type = object · requires: ref, version
	type = object · requires: version
	type = object · requires: version

Properties for Inline timeseries family:

A timeseries family written out in full: where its rows come from, plus what its columns mean.

Source · required

Where the timeseries family's rows come from.

object · required

The timeseries family's columns, keyed by name. Exactly one declares kind: "time".

version

string · const · required

Which schema format this document is written in.

Const value: 0.3

has_gaps

boolean | null

object | null

Roll-up paths, keyed by the name you give each one.

Covariate[]

Other timeseries families to attach, each contributing extra variables.

name

string | null

A name for the timeseries family, for your own reference.

description

string | null

What the timeseries family holds, for your own reference.

metadata

Anything you want to keep alongside the timeseries family. It is stored as written and plays no part in the forecast.

SchemaUri

string

Where another schema document lives: a path to a schema file, relative to the document naming it.

Example: ./sales.json

On

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = object · requires: base, attached

Properties for Time:

Const value: time

Match the two tables on time, at the finest time step both have. When one table steps coarser than the other, such as weekly prices attached to daily sales, each row of the finer table falls in one step of the coarser table: the finer table needs a partition on the coarser table's grid, anchor included. An attached table that steps coarser gives each row of this table its step's value, repeated; one that steps finer is aggregated to this table's step.

OnPair

One pair of columns to match rows on. Two time columns must step on the same grid; "time" matches time columns on different grids.

base

string · required

Column in your main table.

attached

string · required

Column in the attached table.

ColumnName

string

Name of a column in a timeseries.

Selector

Which series to forecast, and at what level of aggregation.

Each key names a level to forecast at: an identifier column, or a time level. Naming "city" in a table with a store → city hierarchy forecasts one series per city, combining its stores as each column's aggregate says ("sum" adds them up). Naming a time level such as "weekly" rolls the data up to weeks the same way before forecasting; the time levels are the time column's own name and the names under its partitions, which by default include weekly, monthly, quarterly and yearly for daily data.

Each value narrows which of that level's values to take:

"any" takes every value.
["Paris", "Lyon"] takes the values listed.
{ "from": "2024-04-01" } takes a range; give from, to or both.

An identifier column you leave out is aggregated away entirely: no entry for store or city forecasts one series for all stores together. Rolling up needs an aggregate on every variable column. Time you leave out stays at the time column's own frequency.

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = string
	type = array
	type = object

Properties for Any:

SelectorAny · enum

Enum values:

any

Select every value at this column — the string "any".

SelectorPattern

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = string
	type = array
	type = object

Properties for Any:

SelectorAny · enum

Enum values:

any

Select every value at this column — the string "any".

SelectorAny

string · enum

Enum values:

any

The string "any": select every value at a column.

SelectorRange

A range of values: { "from": …, "to": … }. Both bounds are optional; give only one for a half-bounded range. The values match the column's type (number, string, or date).

from

Lower bound of the range; omit for an open lower end.

to

Upper bound of the range; omit for an open upper end.

Quantile

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = number
	type = string

Properties for Variant 1:

number · min: 0 · max: 1

MetricsRequest

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = boolean
	type = object

Properties for Toggle:

boolean

true scores with the default settings; false does not score.

MetricsSettings

How to score the forecast.

CrpsWeighting

How crps weighs the quantile levels. Defaults to "trapezoid".

Default: trapezoid

CrpsWeighting

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string

Properties for Variant 1:

Const value: trapezoid

Weighs each level by the width of the probability interval around it, approximating the CRPS integral over `[0, 1]`. Needs at least three levels.

Cutoffs

Cutoff[] · minItems: 1

A non-empty array of information cutoffs. For example ["latest"], an explicit date ["2025-01-31"], or a recurring schedule [{ "every": "3d" }].

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = object · requires: every

Properties for Latest observation:

Latest · enum

Enum values:

latest

The targets' last value, or the earliest of their last values when they end at different times.

Cutoff

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = object · requires: every

Properties for Latest observation:

Latest · enum

Enum values:

latest

The targets' last value, or the earliest of their last values when they end at different times.

Latest

string · enum

Enum values:

latest

The string "latest": cut off at the targets' last value, or at the earliest of their last values when they end at different times.

Datetime

string · pattern: ^\d{4}-\d{2}-\d{2}([…

A date (2025-01-04) or a date and time (2025-01-04T00:00:00Z), in ISO 8601. A time without a UTC offset is read as UTC.

Example 1: 2025-01-04T00:00:00Z

Example 2: 2025-01-04T00:00:00+02:00

Example 3: 2025-01-04T00:00:00

Example 4: 2025-01-04 00:00:00

Example 5: 2025-01-04

RecurringCutoff

A recurring information cutoff: one cutoff every every, repeated across the series. Use this for backtesting or rolling-origin evaluation instead of listing every cutoff date by hand.

every is a whole number of the timeseries' calendar frequency steps, or any calendar interval at least as coarse as the grid: "monthly" on a daily grid cuts monthly on the day selected by the anchor. Bounds are inclusive and resolved separately for each series against its stored time grid, so missing target values never move them; rows appended with NULL targets (e.g. future rows carrying covariates) extend the grid and count toward its last timestamp. Each cutoff observes its containing grid span; the lower bound includes its entire containing span, even when a cutoff precedes the start instant within that span. Only cutoffs on the series' stored time grid are admitted, even when a bound lies outside it: a start before the first stored timestamp admits every cutoff from there on, without changing the alignment.

For example, the last 6 evaluation origins of a 48-step horizon, each leaving a full horizon of stored rows after it: { "every": 48, "start": -288, "end": 48, "anchor": "end" }.

StepsOrDuration · required

A length of time: a number of steps of the data's time grid, or a duration string. With daily data, 7 and "1w" are the same. A duration must be a whole number of steps: "1mo" does not fit daily data, and "1d" does not fit monthly data.

CutoffBound

Absolute start, or an offset from a series boundary: nonnegative counts forward from the first stored timestamp, negative counts backward from the last. Defaults to 0, the first stored timestamp.

Default: 0

CutoffBound

Absolute end, or an offset from a series boundary: nonnegative counts backward from the last stored timestamp, negative counts forward from the first. Defaults to 0, the last stored timestamp.

Default: 0

anchor

CutoffAnchor · enum

Align to the resolved start or end, defaulting to the end.

Enum values:

start

end

Default: end

StepsOrDuration

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = integer
	type = string

Properties for Steps:

integer · int32

A whole number of steps of the data's time grid, such as 7.

Duration

string

A length of time, written in one of three ways:

Numbers with units, separated by spaces: 28d, 2w, 1d 12h. The units are y (years), q (quarters), mo (months), w (weeks), d (days), h (hours), m (minutes), s (seconds) and us (microseconds). They are lowercase, and m is minutes, not months.
A name: yearly, quarterly, monthly, weekly, daily, hourly, minute, second, 5min, 10min, 15min or 30min.
An ISO 8601 duration, in capitals: P1M, P2W, PT1H30M.

The length must be more than zero. Responses always write durations in ISO 8601, without weeks: two weeks read P14D.

Example 1: 28d

Example 2: 2w

Example 3: 1d 12h

Example 4: monthly

Example 5: P1M

CutoffBound

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = string
	type = integer
	type = string

Properties for At:

Datetime · pattern: ^\d{4}-\d{2}-\d{2}([…

An absolute instant (e.g. "2025-01-31").

Example 1: 2025-01-04T00:00:00Z

Example 2: 2025-01-04T00:00:00+02:00

Example 3: 2025-01-04T00:00:00

Example 4: 2025-01-04 00:00:00

Example 5: 2025-01-04

SignedDuration

string

A duration (1mo, 1d 3h, P1M), or one pointing backward, with a - before every term (-1mo, -1d -3h, -P1M).

Example 1: 1mo

Example 2: -1mo

Example 3: P2W

Example 4: -P2W

CutoffAnchor

string · enum

Enum values:

start

end

Boundary that aligns the recurrence: forward from start or backward from end. Clipping to the stored time grid does not change this alignment.

LeadTime

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = integer
	type = string

Properties for Steps:

integer · int32

A whole number of steps of the data's time grid, such as 7.

Context

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = integer
	type = string

Properties for Steps:

integer · int32

A whole number of steps of the data's time grid, such as 7.

PredictionLength

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = integer
	type = string

Properties for Steps:

integer · int32

A whole number of steps of the data's time grid, such as 7.

Span

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = integer
	type = string

Properties for Steps:

integer · int32

A whole number of steps of the data's time grid, such as 7.

ForecastResponse

ForecastTable · required

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.

array | null

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.

ForecastTable

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.

time

Datetime[] · required

Target time of the prediction: one step past cutoff, plus lead_time.

cutoff

Datetime[] · required

Information cutoff the prediction was made from, the last instant it saw.

lead_time

Duration[] · required

How far ahead the row is: the request's lead_time plus the row's step within its forecast, as an ISO 8601 duration. A daily forecast with no lead_time reads PT0S, P1D, P2D, …

span

Duration[] · required

Time interval each value covers, as an ISO 8601 duration: P1D for a daily total.

object · required

Which series each row belongs to, keyed by identifier column: the columns the selector names, plus the coarser columns above them in their hierarchies. A column is null on rows aggregated above it — a per-city total has a null store.

object · required

Forecast values, keyed by target column. Each target's quantiles maps a level's label ("0.1", "0.5", "mean") to one value per row.

object | null

Each target's actual value at time, null where it has none. Present only when the request set return_actuals.

ColumnValues

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = array
	type = array
	type = array
	type = array
	type = array
	type = array
	type = array

Properties for Integers:

integer[]

TargetForecast

object · required

SeriesMetrics

Accuracy for one timeseries of the timeseries family at one information cutoff, keyed by target column.

object · required

The series' identifier values, as the response dataframe's identifiers columns carry them.

cutoff

Datetime · pattern: ^\d{4}-\d{2}-\d{2}([… · required

Information cutoff the scored forecast was made from.

Example 1: 2025-01-04T00:00:00Z

Example 2: 2025-01-04T00:00:00+02:00

Example 3: 2025-01-04T00:00:00

Example 4: 2025-01-04 00:00:00

Example 5: 2025-01-04

object · required

Value

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = null
	type = string
	type = integer
	type = boolean

Properties for Null:

null

Metrics

Accuracy for one target: the distribution scored over the requested quantile levels, and a point forecast scored by mae, mape, wape and scaled_bias. The point forecast is the 0.5 quantile when requested, and the mean otherwise. A field is null where the metric does not apply — the CRPS under three levels with the "trapezoid" weighting, mape when every actual is zero or missing, a scaled metric whose actuals are all zero, every metric when the target has no observed actual over the forecast window. Missing actuals are skipped: each metric averages over the window's observed steps, and mape also skips zero actuals.

crps

number | null · double

Continuous ranked probability score, from the pinball loss of each requested quantile level weighed as compute_metrics.crps says: "trapezoid", the default, approximates the CRPS integral; "mean_quantile_loss" is twice the mean pinball loss over the levels. The response does not say which weighting was used.

scaled_crps

number | null · double

crps divided by the mean absolute observed actual over the forecast window. It is scaled per window, so its average across windows is not the scaled CRPS of the whole dataset.

mae

number | null · double

Mean absolute error of the point forecast.

mape

number | null · double

Mean absolute percentage error of the point forecast, as a fraction, not a percentage.

wape

number | null · double

mae divided by the mean absolute observed actual over the forecast window.

scaled_bias

number | null · double

Mean signed error of the point forecast, prediction - actual, divided by the mean absolute observed actual over the forecast window: negative when the forecast runs low.

SeriesForecast

One timeseries forecast for one information cutoff datetime.

A streamed response (application/x-ndjson or application/vnd.msgpack) is a sequence of these records, one for each timeseries and cutoff, sent as each forecast is ready.

Example

A daily sales forecast for store 42, made with data up to 2024-03-31:


Code
{
  "identifiers": { "store": 42 },
  "cutoff": "2024-03-31T00:00:00Z",
  "origin": "2024-01-01T00:00:00Z", "first_step": 91,
  "lead_time": "PT0S", "frequency": "P1D", "span": "P1D",
  "targets": { "sales": { "quantiles": {
    "0.1": [118, 121, 97], "0.5": [140, 144, 121], "0.9": [166, 170, 148]
  } } }
}

Forecast times

Each quantile holds one value per forecast step, in time order. The times are not listed; compute them from origin, first_step and frequency: the value at index i (counting from 0) is the forecast for

Code
origin + (first_step + i) × frequency

In the example, origin is January 1 and first_step is 91, so the three values are the forecasts for April 1, 2 and 3.

Why `origin` and `first_step`?

A single start time would not be enough: each time must be computed from origin directly, not by adding frequency to the previous time. On a monthly series the two can disagree, because months have different lengths. With origin = 2024-01-31 and frequency = P1M:

Code
counting from origin:       Jan 31, Feb 29, Mar 31, Apr 30
adding one month each time: Jan 31, Feb 29, Mar 29, Apr 29

object · required

The series' identifier values, keyed by source column name: its selected levels and their hierarchy ancestors.

cutoff

Datetime · pattern: ^\d{4}-\d{2}-\d{2}([… · required

Information cutoff the series was forecast from, the last instant it saw.

Example 1: 2025-01-04T00:00:00Z

Example 2: 2025-01-04T00:00:00+02:00

Example 3: 2025-01-04T00:00:00

Example 4: 2025-01-04 00:00:00

Example 5: 2025-01-04

origin

Datetime · pattern: ^\d{4}-\d{2}-\d{2}([… · required

Start of the series' first step: the span holding its first observation.

Example 1: 2025-01-04T00:00:00Z

Example 2: 2025-01-04T00:00:00+02:00

Example 3: 2025-01-04T00:00:00

Example 4: 2025-01-04 00:00:00

Example 5: 2025-01-04

first_step

integer · uint32 · min: 0 · required

Steps from origin to the first value.

lead_time

Duration · required

Gap held between the step after cutoff and the first value.

Example 1: 28d

Example 2: 2w

Example 3: 1d 12h

Example 4: monthly

Example 5: P1M

frequency

Duration · required

Time between consecutive values.

Example 1: 28d

Example 2: 2w

Example 3: 1d 12h

Example 4: monthly

Example 5: P1M

span

Duration · required

Target-time interval covered by each value.

Example 1: 28d

Example 2: 2w

Example 3: 1d 12h

Example 4: monthly

Example 5: P1M

object · required

The forecast values, keyed by target column, then by quantile label.

object | null

The actuals, keyed by target column: one per forecast value, null where the target has none. Present only when the request set return_actuals.

object | null

Accuracy of this forecast, keyed by target column. Present only when the request set compute_metrics and some target is observed across its values.

StreamError

The last record of a stream a failure cut short.

Problem · required

What went wrong, as a problem response reports it.

Example:

{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "unprocessable",
  "detail": "unknown target column `revenue`"
}{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "unprocessable",
  "detail": "unknown target column `revenue`"
}

Problem

An error, as an RFC 9457 problem document.

type

string · required

A URI naming the kind of problem. Always about:blank: code tells the kinds apart.

title

string · required

The HTTP status phrase, such as Unprocessable Entity.

status

integer · uint16 · min: 0 · max: 65535 · required

The HTTP status code, repeated from the response.

ProblemCode · required

What kind of error this is, stable across releases: match on this, not on title or detail.

detail

string · required

What went wrong with this request, for a person to read. The wording may change.

ProblemCode

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = string
	type = string
	type = string
	type = string
	type = string
	type = string
	type = string
	type = string
	type = string
	type = string
	type = string
	type = string

Properties for Variant 1:

Const value: bad_request

The request is malformed: unreadable JSON, a missing `query` part, a field of the wrong type.