The Forecasting API is now v1. API v0 is deprecated and stops working on 20 December 2026. Move to v1
The Forecasting Company Logo

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, how the column schema, selectors, hierarchies and backtests fit together, with interactive examples.
  • Cookbook, complete, runnable requests for common tasks: several targets, roll-ups, backtests, parquet files, covariates.
  • Error handling, what each error means and which ones to retry.
  • API Reference, every field, parameter and error status.

Quick start

Daily sales for one store, forecast two weeks ahead:

TerminalCode
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:

JSONCode
{ "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 page.

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

ModelDescription
t0-gammaThe Forecasting Company's latest model
t0-betaThe Forecasting Company's previous model
t0-alphaThe Forecasting Company's first model
chronos-2Amazon's Chronos-2
timesfm-2p5Google's TimesFM 2.5
tirexNXAI's model based on xLSTMs
toto2Datadog's Toto v.2
tabpfn-2Foundation model from Uni. of Freiburg
tabiclTabICL, a tabular in-context learner
aarimaAuto-ARIMA
aetsAuto-ETS
naiveSeasonal naive baseline

Questions? Email [email protected].

Last modified on