Copy page

Forecasting API

Endpoints

The API Reference is the source of truth for this API: it is generated from the OpenAPI spec the gateway actually serves, and carries the full request and response schemas, every query parameter, worked request examples and a console you can call the API from. The spec itself is at https://api.retrocast.com/openapi, no authentication required.

This page covers what the reference can't: which endpoint to reach for, and how to read what comes back.

Choosing an endpoint

Both forecast endpoints take the same request body, so moving a request from one to the other is a change of URL, not of payload.

Reading a forecast

series is a nested array: series[i][j] is the prediction for the i-th input series at the j-th forecast creation date. A request with one series and no fcds gets back series[0][0].

Each prediction carries:

• prediction — a map of quantile → values. Always includes mean; the other keys are the quantiles you asked for.
• index — the dates the forecast covers.
• metrics — accuracy scores, present only when the true target is known (so: during backtesting). mae, mape, crps, wape and scaled_bias, each nullable.

Polling a job

GET /forecast-jobs/{job_id} returns one of three shapes, and you switch on status:

• in_progress — nothing else in the body. Poll again.
• completed — carries series, in the same shape as a synchronous forecast.
• failed — carries error with a machine-readable code and a human-readable message. The job failed permanently; don't retry it.

Backtesting with forecast creation dates

fcds is a list of indexes into target, each marking a point in history to forecast from. One request with several fcds returns one forecast per date — that's a rolling-origin backtest, and because the true values are known, each prediction comes back with metrics.

This is the usual reason to prefer POST /forecast-jobs: a backtest over many dates is exactly the long-running case the synchronous endpoint isn't meant for.

Series that only lend context

Setting only_as_context: true on a series feeds it to the model without forecasting it. Use it to let a global model see related history — sibling stores, earlier product generations — without paying for predictions you'll discard. It applies to global models only.

Pinning cloud and region

/forecast and /warmup accept optional cloud (gcp or aws) and region (us or eu) query parameters. Leave them unset and any available combination may serve the request; set them when residency or locality matters.