Endpoints

Welcome to the TFC API. If you have any issues or feedback please get in touch with us at [email protected].

Model inference

POST

https://api.retrocast.com

/forecast

Perform inference with foundation models.

Model inference › query Parameters

model

string · enum · required

The forecasting model to use for inference. Note that only t0-gamma, t0-beta, t0-alpha, tabpfn-2, moirai-2, and chronos-2 support exogenous variables.

Enum values:

t0-gamma

t0-beta

t0-alpha

timesfm-2p5

moirai-2

tabpfn-2

tirex

aets

Default: t0-gamma

cloud

string · enum

Specify the cloud provider to use for inference. If none is set then any may be used depending on availability, including clouds not present in the below list (e.g. Oracle).

Enum values:

gcp

aws

region

string · enum

Specify the region to use. If none is set then any may be used depending on availability, including regions not available for direct selection (such as ap or uk). Note that the region specifies the region for processing, but the request still passes through a control plane in the US.

Enum values:

Model inference › Request Body

API request model for the model inference endpoint.

object[] · required

horizon

integer · min: 1 · max: 10000 · required

Number of steps to forecast given the frequency.

Example: 5

freq

string · enum · required

Frequency of the time series.

Enum values:

10S

min

5min

10min

15min

30min

Example: D

context

integer | null · min: 1

The amount of history to use when forecasting. This is the number of steps to look back in the target series. More history can improve the forecast accuracy, but can also increase the computation time. By default this is set to the max of model capability or the length of the provided target series, whichever is shorter.

Example: 20

Default: null

quantiles

number[] | null

Default: [0.1, 0.9, 0.4, 0.5]

array | null

Apply additional co-variates provided by TFC. Only supported by the following models: Moirai-2, Chronos-2 and TabPFN-2.

Example: {"0": {"config": {"country": "US"}, "type": "holidays"}}

Default: null

Optional model-specific configuration overrides.

Example: {"config": {"season_length": 7}, "model": "aarima"}

Default: null

Model inference › Responses

Success

Synchronous POST /forecast response. Always carries a completed forecast.

array[] · required

Per-input-series predictions.

POST/forecast

curl 'https://api.retrocast.com/forecast?model=t0-gamma' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "series": [
    {
      "index": [
        "2001-01-06",
        "2001-01-07",
        "2001-01-08",
        "2001-01-09",
        "2001-01-10"
      ],
      "target": [
        125,
        120,
        140,
        135,
        133
      ]
    }
  ],
  "horizon": 5,
  "freq": "D",
  "context": null,
  "quantiles": [
    0.1,
    0.9,
    0.4,
    0.5
  ]
}'

Example Request Body

{
  "series": [
    {
      "index": [
        "2001-01-06",
        "2001-01-07",
        "2001-01-08",
        "2001-01-09",
        "2001-01-10"
      ],
      "target": [
        125,
        120,
        140,
        135,
        133
      ]
    }
  ],
  "horizon": 5,
  "freq": "D",
  "context": null,
  "quantiles": [
    0.1,
    0.9,
    0.4,
    0.5
  ]
}

json

application/json

Example Responses

{
  "series": [
    [
      {
        "prediction": {
          "0.1": [
            1,
            2,
            3
          ],
          "0.9": [
            1,
            2,
            3
          ],
          "mean": [
            1,
            2,
            3
          ]
        },
        "index": [
          "string"
        ],
        "metrics": null
      }
    ]
  ]
}

json

application/json

Submit job for forecasting

POST

https://api.retrocast.com

/forecast-jobs

Perform historic inference for a range of forecast creation dates (fcds). These jobs can run longer and need to be retrieved with a separate endpoint and the returned job ID.

Submit job for forecasting › query Parameters

model

string · enum · required

The forecasting model to use for inference. Note that only t0-gamma, t0-beta, t0-alpha, tabpfn-2, moirai-2, and chronos-2 support exogenous variables.

Enum values:

t0-gamma

t0-beta

t0-alpha

timesfm-2p5

moirai-2

tabpfn-2

tirex

aets

Default: t0-gamma

Submit job for forecasting › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Submit job for forecasting › Request Body

API request model for the model inference endpoint.

object[] · required

horizon

integer · min: 1 · max: 10000 · required

Number of steps to forecast given the frequency.

Example: 5

freq

string · enum · required

Frequency of the time series.

Enum values:

10S

min

5min

10min

15min

30min

Example: D

context

integer | null · min: 1

Example: 20

Default: null

quantiles

number[] | null

Default: [0.1, 0.9, 0.4, 0.5]

array | null

Apply additional co-variates provided by TFC. Only supported by the following models: Moirai-2, Chronos-2 and TabPFN-2.

Example: {"0": {"config": {"country": "US"}, "type": "holidays"}}

Default: null

Optional model-specific configuration overrides.

Example: {"config": {"season_length": 7}, "model": "aarima"}

Default: null

Submit job for forecasting › Responses

Job submitted successfully. The returned job_id is used to poll GET /forecast-jobs/{job_id} for results.

POST /forecast-jobs response. Carries the identifier used to poll for results.

job_id

string · required

Unique identifier for the submitted job. Use it with GET /forecast-jobs/{job_id} to poll for results.

POST/forecast-jobs

curl 'https://api.retrocast.com/forecast-jobs?model=t0-gamma' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "series": [
    {
      "index": [
        "2001-01-06",
        "2001-01-07",
        "2001-01-08",
        "2001-01-09",
        "2001-01-10"
      ],
      "target": [
        125,
        120,
        140,
        135,
        133
      ]
    }
  ],
  "horizon": 5,
  "freq": "D",
  "context": null,
  "quantiles": [
    0.1,
    0.9,
    0.4,
    0.5
  ]
}'

Example Request Body

{
  "series": [
    {
      "index": [
        "2001-01-06",
        "2001-01-07",
        "2001-01-08",
        "2001-01-09",
        "2001-01-10"
      ],
      "target": [
        125,
        120,
        140,
        135,
        133
      ]
    }
  ],
  "horizon": 5,
  "freq": "D",
  "context": null,
  "quantiles": [
    0.1,
    0.9,
    0.4,
    0.5
  ]
}

json

application/json

Example Responses

{
  "job_id": "job_id"
}

json

application/json

Retrieve job result

GET

https://api.retrocast.com

/forecast-jobs/{job_id}

Retrieve the forecast result from a forecast job.

Retrieve job result › path Parameters

job_id

string · required

Retrieve job result › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Retrieve job result › Responses

Job state. Switch on status — completed carries series, failed carries error, in_progress means keep polling.

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · status="completed" · requires: series
	type = object · status="in_progress"
	type = object · status="failed" · requires: error

Properties for JobCompleted:

Async polling response when the job finished successfully.

status

string · const · required

Const value: completed

array[] · required

Per-input-series predictions.

OpenAPI spec

GET

https://api.retrocast.com

/openapi

Return the OpenAPI spec for the TFC API.

OpenAPI spec › Responses

Rate Limiting Response

type

string · required

A URI reference that identifies the problem.

title

string · required

A short, human-readable summary of the problem.

status

number · required

The HTTP status code.

instance

string

Warmup model

GET

https://api.retrocast.com

/warmup

Warmup a model endpoint for better UX in embedded applications.

Warmup model › query Parameters

model

string · enum · required

The forecasting model to warmup.

Enum values:

t0-gamma

t0-beta

t0-alpha

timesfm-2p5

moirai-2

tabpfn-2

tirex

aets

Default: t0-gamma

cloud

string · enum

Specify the cloud provider to use. If none is set then any may be used depending on availability, including clouds not present in the below list (e.g. Oracle).

Enum values:

gcp

aws

region

string · enum

Enum values:

Warmup model › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Warmup model › Responses

Rate Limiting Response

type

string · required

A URI reference that identifies the problem.

title

string · required

A short, human-readable summary of the problem.

status

number · required

The HTTP status code.

instance

string