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


# Overview

Welcome to The Forecasting Company API. We expose our own models, as
well as other open-source foundation models, behind a unified REST API at
`https://api.retrocast.com`.

This page gets you to a first forecast: a quick start, authentication and the
available models. The rest of the documentation:

- [Concepts](/api-v1/contents/intro), how the column schema, selectors,
  hierarchies and backtests fit together, with interactive examples.
- [Cookbook](/api-v1/contents/cookbook), complete, runnable requests for
  common tasks: several targets, roll-ups, backtests, parquet files,
  covariates.
- [Error handling](/api-v1/contents/errors), what each error means and
  which ones to retry.
- [API Reference](/api-v1/contents/api-reference), every field, parameter
  and error status.

## Quick start

Daily sales for one store, forecast two weeks ahead:

```bash
curl -X POST "https://api.retrocast.com/v1/forecast?model=t0-gamma" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "source": {
        "inline": {
          "date":  ["2024-01-01", "2024-01-02", "2024-01-03"],
          "store": ["S1", "S1", "S1"],
          "sales": [142, 137, 145]
        }
      },
      "columns": {
        "date":  { "kind": "time", "frequency": "1d" },
        "store": "identifier",
        "sales": { "kind": "target", "aggregate": "sum" }
      }
    },
    "prediction_length": "2w",
    "quantiles": [0.1, 0.5, 0.9]
  }'
```

`input.source` holds the data, here inline with one array per column.
`input.columns` gives each column a role: `date` is the time axis, `store`
identifies a series, `sales` is the value to forecast. Each distinct `store`
is one series.

The response has one entry per series and forecast step. The arrays below are
trimmed to the first two of the 14 steps:

```json
{
  "data": {
    "time":      ["2024-01-04T00:00:00Z", "2024-01-05T00:00:00Z"],
    "cutoff":    ["2024-01-03T00:00:00Z", "2024-01-03T00:00:00Z"],
    "lead_time": ["PT0S", "P1D"],
    "span":      ["P1D", "P1D"],
    "identifiers": { "store": ["S1", "S1"] },
    "targets": {
      "sales": { "quantiles": { "0.1": [137.7, 137.5], "0.5": [141.0, 140.5], "0.9": [147.4, 146.2] } }
    }
  }
}
```

## Authentication

Every request needs an API key, sent as a Bearer token. Create one on the
[API Keys](/settings/api-keys) page.

```
Authorization: Bearer YOUR_API_KEY
```

## Available models

The `model` query parameter is required; a request without it is rejected
with `missing field "model"`. `t0-gamma` is our latest model.

To pass options to the model, put them in the request's `model_config` field.
They go to the model as given: each model defines which options it takes, and
rejects the ones it doesn't know.

{/* TODO(TFC-3487): this list is hand-copied from navi's apps/models/catalog.toml
    (entries with visibility = "public"). Generate it from the catalog once the
    public API moves into navi: https://linear.app/t21y/issue/TFC-3487/move-public-api-to-navi */}

| Model         | Description                                |
| ------------- | ------------------------------------------ |
| `t0-gamma`    | The Forecasting Company's latest model     |
| `t0-beta`     | The Forecasting Company's previous model   |
| `t0-alpha`    | The Forecasting Company's first model      |
| `chronos-2`   | Amazon's Chronos-2                         |
| `timesfm-2p5` | Google's TimesFM 2.5                       |
| `tirex`       | NXAI's model based on xLSTMs               |
| `toto2`       | Datadog's Toto v.2                         |
| `tabpfn-2`    | Foundation model from Uni. of Freiburg     |
| `tabicl`      | TabICL, a tabular in-context learner       |
| `aarima`      | Auto-ARIMA                                 |
| `aets`        | Auto-ETS                                   |
| `naive`       | Seasonal naive baseline                    |

Questions? Email support@theforecastingcompany.com.
