Developer documentation API v1
Aura forecast contracts
Represent predictions as versioned conditional distributions with explicit targets.
Reading a predictive distribution
Forecast object
F is a conditional predictive distribution; θ identifies a frozen model revision; I_t is the eligible information set; h is a specified horizon. The illustrated target is a simple price return. Currency, session calendar, endpoint price convention and corporate-action treatment are part of the target definition.
Forecast request
POST /v1/forecasts returns a 202 job reference. Specify the instrument, origin, target, horizon, evidence snapshot and model revision. The following request and artifact illustrate the same forecast lifecycle.
{
"instrument_id": "equity:listing:apple-common-xnas",
"origin_at": "2026-10-01T20:05:00Z",
"target": "simple_price_return",
"horizon": {"value": 5, "unit": "trading_sessions"},
"evidence_snapshot_id": "snap_example_1",
"model_revision": "aura-example-r1"
}Forecast artifact
Example values correspond to the illustrative distribution above, rounded to six decimal places.
{
"forecast_id": "fc_example_1",
"instrument_id": "equity:listing:apple-common-xnas",
"origin_at": "2026-10-01T20:05:00Z",
"target": "simple_price_return",
"horizon": {
"value": 5,
"unit": "trading_sessions"
},
"unit": "fraction",
"model_revision": "aura-example-r1",
"evidence_snapshot_id": "snap_example_1",
"estimate": {
"mean": 0.0218,
"quantiles": {
"0.05": -0.035438,
"0.50": 0.015574,
"0.95": 0.101898
}
},
"evaluation_state": "pending_outcome"
}Validation and abstention
Forecast admission checks the target, horizon, instrument domain and temporal eligibility of the evidence snapshot. An unsupported domain or insufficient input produces an explicit outcome instead of a fabricated probability. Quantile levels lie in (0,1), values are monotonic across levels, and event probabilities lie in [0,1].
Abstention is a model-service outcome: the available information does not support the requested prediction under the selected model contract. It differs from an operational failure and from a forecast with a near-zero mean. A sparse quantile set does not uniquely specify a mean, density or tail probability.
Outcome materialization
The forecast artifact is frozen before its outcome becomes observable. After the horizon closes, the outcome record references the exact target definition, endpoint observations and evidence revisions. Missing outcomes retain a reason rather than entering a score as zero.
Forecast revisions, model revisions and evaluation-method revisions are separate identities. Recomputing a metric changes the evaluation record, not the prediction being evaluated. Calibration, discrimination and portfolio utility remain distinct measurements because a statistically useful forecast can still be uneconomic after costs.
Quantiles and interval probability
Q is a quantile of the conditional forecast distribution F. For a continuous distribution with the relevant quantiles, the central interval contains nominal probability 1−α. Atoms, interpolation and finite quantile grids require their declared conventions. This is a prediction interval for an outcome, not a confidence interval for an estimated mean.
Sources of predictive uncertainty
Market uncertainty reflects variation in future outcomes even under a fixed model and information set. Estimation uncertainty reflects limited data, model selection and parameter uncertainty. A reported predictive distribution can contain both, but its mean and quantiles alone do not identify their separate contributions.
The forecast contract therefore reports the target distribution and model revision without implying an unobserved decomposition. Horizon, calendar, endpoint price and corporate-action treatment define the random variable. Changing any of them changes the prediction task, even if the interface still displays an expected return.
Distribution-to-decision semantics
A mean summarizes expected value under a distribution; a quantile describes an outcome threshold. Neither directly determines position size. Portfolio construction combines the forecast with joint risk, current holdings, liquidity and costs.
For example, a positive expected return can coexist with substantial probability of loss. A narrow central interval can still omit economically important tail scenarios. Evaluation and portfolio diagnostics therefore inspect more than the direction of the mean.