# Endpoints

> For AI agents: the complete documentation index is at
> [https://docs.retrocast.com/llms.txt](https://docs.retrocast.com/llms.txt) — every page is also available as
> markdown by appending `.md` to its URL.

The [API Reference](/api/endpoints) 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](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

| Endpoint | Reach for it when |
| --- | --- |
| `POST /forecast` | You want forecasts in the response. The default path. |
| `POST /forecast-jobs` | The work is long-running — backtesting across many forecast creation dates, or a slow statistical model. Returns a `job_id` instead of a forecast. |
| `GET /forecast-jobs/{job_id}` | Polling a submitted job. |
| `GET /warmup` | Pre-loading a model. Cold models cost a few seconds on the first inference call; warming up hides that from your users. |
| `GET /openapi` | Fetching the spec, unauthenticated. |

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.