Add extra data like weather or prices

Other series affect your target: weather, promotions, prices. They usually live in a separate table. covariates attaches that table to your input and matches its rows to yours by key, so you don't have to join them yourself:

Code
{
  "input": {
    "source": {
      "inline": {
        "date":  ["2024-01-01", "2024-01-02", "2024-01-03"],
        "sales": [142, 137, 145]
      }
    },
    "columns": {
      "date":  { "kind": "time", "frequency": "1d" },
      "sales": { "kind": "target" }
    },
    "covariates": [
      {
        "schema": {
          "version": "0.3",
          "source": {
            "inline": {
              "date":        ["2024-01-01", "2024-01-02", "2024-01-03"],
              "temperature": [4.5, 3.1, 6.0]
            }
          },
          "columns": {
            "date":        { "kind": "time", "frequency": "1d" },
            "temperature": "historical"
          }
        },
        "on": [{ "base": "date", "attached": "date" }]
      }
    ]
  },
  "prediction_length": "1w"
}

Post it to https://api.retrocast.com/v1-beta/forecast?model=t0-alpha. model names the forecasting model and is required — without it the request is rejected with missing field "model".

on lists the columns to match on — here the base date against the attached date. temperature then behaves like a column of the base series.

Two things to watch:

• on: [] matches every attached row to every base row.
• Leaving on out is not the same as on: []. The request is rejected, so always list the pairs.

Use only to keep a subset of the attached columns, or rename to rename them.

Each extra table stays where it is. Attach weather, prices and promotions separately instead of maintaining one wide pre-joined table.

What comes back

Only your targets. The attached columns change the forecast but are not echoed back:

Code
{
  "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": {},
    "targets": {
      "sales": {
        "quantiles": {
          "0.1":  [137.6, 137.5],
          "0.5":  [141.0, 140.5],
          "0.9":  [147.4, 146.1],
          "mean": [141.6, 141.0]
        }
      }
    }
  }
}

There is no temperature entry — it was an input, not something to forecast. To get a forecast for it too, make it a column of your base series with the "target" kind instead. See Forecast several columns at once.