# Covariates

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

Covariates are additional variables that can improve forecast accuracy. They come in two forms:

## User-provided covariates

Pass these directly in the `series` objects:

- **`hist_variables`** — variables with values only for the historical period (same length as `target`). Example: recorded temperature.
- **`future_variables`** — variables with values for both history and forecast period. Length = history + horizon. Example: planned promotions, weather forecasts.
- **`static_variables`** — variables that don't change over time. Single numeric value per variable. Example: population, store size.

## TFC-provided covariates

Use the `covariates` array in the request body to automatically add covariates managed by TFC:

### Holidays

```json
{
  "type": "holidays",
  "config": {
    "country": "US",
    "smoothing_method": "auto",
    "window_size": 15,
    "sigma": 7.0,
    "ramp_days": 14
  }
}
```

- `country` (required): 2-character ISO country code (e.g., `US`, `GB`, `FR`, `DE`)
- `smoothing_method`: `auto` (default), `none`, `gaussian`, `exponential`, `ramp`, `flat`
- `window_size`: 1–15 (default 15), should be odd
- `sigma`: standard deviation for Gaussian kernel (default 7.0)
- `ramp_days`: days before/after for ramp (1–35, default 14)

### Events

```json
{
  "type": "events",
  "config": {
    "country": "US"
  }
}
```

- `country` (required): ISO country code or `"Global"`

### Temporal features

```json
{
  "type": "temporal_features",
  "config": {}
}
```

Automatically adds time-based features (day of week, month, etc.).