> 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, as well as open-source foundation models,
behind a unified REST API at `https://api.retrocast.com`.

This page covers the quick start, authentication, the available models and the
supported frequencies. The rest of the documentation:

- [Endpoints](/documentation/endpoints) — which endpoint to reach for, and how to
  read a forecast, poll a job and run a backtest. Parameters, schemas and worked
  examples live in the [API Reference](/api/endpoints).
- [Covariates](/documentation/covariates) — exogenous variables you provide, and
  holidays, events and temporal features we provide.
- [Model-specific configuration](/documentation/model-config) — the `model_config`
  overrides accepted by Auto-ARIMA, Auto-ETS and Chronos-2.
- [Python SDK](/documentation/python-sdk) — the higher-level
  `theforecastingcompany` client.
- [Error handling](/documentation/errors) — status codes and how to reach us.

## Quick start

```bash
curl -X POST "https://api.retrocast.com/forecast?model=tabpfn-ts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "series": [{
      "index": ["2024-01-01","2024-01-02","2024-01-03","2024-01-04","2024-01-05"],
      "target": [125, 120, 140, 135, 133]
    }],
    "horizon": 5,
    "freq": "D",
    "quantiles": [0.1, 0.5, 0.9]
  }'
```

Or with the **Python SDK**:

```bash
pip install theforecastingcompany
```

```python
from theforecastingcompany import TFCClient, TFCModels

client = TFCClient()  # reads TFC_API_KEY from environment

forecast_df = client.forecast(
    train_df,
    model=TFCModels.TabPFN_TS,
    horizon=12,
    freq="W",
    quantiles=[0.1, 0.5, 0.9],
)
```

## Authentication

All API requests require a Bearer token. Obtain your API key at
[https://docs.retrocast.com/settings/api-keys](https://docs.retrocast.com/settings/api-keys).

Include it in every request header:

```
Authorization: Bearer YOUR_API_KEY
```

## Available models

`t0-gamma` is the latest model and the default selection.

| Model          | Description                              | Covariates?            | Forecast? | Backtest? |
| -------------- | ---------------------------------------- | ---------------------- | --------- | --------- |
| `t0-gamma`     | The Forecasting Company's latest model   | ✅                     | ✅        | ✅        |
| `t0-beta`      | The Forecasting Company's previous model | ✅                     | ✅        | ✅        |
| `t0-alpha`     | The Forecasting Company's model          | ✅                     | ✅        | ✅        |
| `tfc-global`   | Global model for time series             | ✅                     | ✅        | ✅        |
| `tabpfn-ts`    | Foundation model from Uni. of Freiburg   | ✅                     | ✅        | ✅        |
| `moirai-2`     | Salesforce's Moirai v.2                  | ✅                     | ✅        | ✅        |
| `timesfm-2`    | Google's TimesFM 2.0                     | Future covariates only | ✅        | ✅        |
| `timesfm-2p5`  | Google's TimesFM 2.5                     | Future covariates only | ✅        | ✅        |
| `chronos-2`    | Amazon's Chronos-2                       | ✅                     | ✅        | ✅        |
| `tirex`        | NXAI's model based on xLSTMs             | ❌                     | ✅        | ✅        |
| `tirex-2`      | NXAI's successor to `tirex`              | Historical & future    | ✅        | ✅        |
| `aarima`       | Auto-ARIMA                               | Soon                   | ✅        | ✅        |
| `aets`         | Auto-ETS                                 | Soon                   | ✅        | ✅        |
| `toto-2`       | Datadog's Toto v.2                       | ❌                     | ✅        | ✅        |

### Models that support exogenous variables (covariates)

`t0-gamma`, `t0-beta`, `t0-alpha`, `tabpfn-ts`, `moirai-2`, and `chronos-2` support full exogenous variables.
`timesfm-2` and `timesfm-2p5` support future covariates only.
`tirex-2` supports historical and future covariates, but not static variables.
`tfc-global` supports all covariate types including string covariates and static variables.

### Models that support string covariates

Only `tabpfn-ts` and `tfc-global` support non-numeric (string) covariates. All other models require numeric covariates only.

## Supported frequencies

The `freq` field must be one of:

| Value   | Meaning       |
| ------- | ------------- |
| `10S`   | 10 seconds    |
| `min`   | 1 minute      |
| `5min`  | 5 minutes     |
| `10min` | 10 minutes    |
| `15min` | 15 minutes    |
| `30min` | 30 minutes    |
| `H`     | Hourly        |
| `D`     | Daily         |
| `W`     | Weekly        |
| `M`     | Monthly       |
| `Q`     | Quarterly     |
| `Y`     | Yearly        |