# Forecast weekly or monthly totals

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

Your table is one row per day, but you plan by the week. Name a coarser time
level in `selector`, and every day is added into its week before the forecast
runs:

```json
{
  "input": {
    "source": {
      "inline": {
        "date":  ["2024-01-01", "2024-01-02", "2024-01-03", "2024-01-04", "2024-01-05", "2024-01-06", "2024-01-07",
                  "2024-01-08", "2024-01-09", "2024-01-10", "2024-01-11", "2024-01-12", "2024-01-13", "2024-01-14"],
        "sales": [142, 137, 145, 139, 160, 188, 95,
                  150, 141, 139, 144, 158, 191, 99]
      }
    },
    "columns": {
      "date":  { "kind": "time", "frequency": "daily" },
      "sales": { "kind": "target", "aggregate": "sum" }
    }
  },
  "selector": { "weekly": "any" },
  "prediction_length": 4
}
```

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

What each part does:

- `"weekly"` is a time level the API adds for you. Daily data gets `weekly`,
  `monthly`, `quarterly` and `yearly`; monthly data gets `quarterly` and
  `yearly`. Weeks run Monday to Sunday.
- `"aggregate": "sum"` says how days combine into a week, so this forecasts
  weekly totals. `"mean"` would forecast the average day of each week instead.
  Every variable column needs an `aggregate` once you roll up — the request is
  rejected without one.
- `"prediction_length": 4` is four weeks: once the forecast is weekly, a step
  is a week. `"4w"` and `"28d"` mean the same; `"1mo"` doesn't fit a whole
  number of weeks and is rejected.

Weeks your data only partly covers, at either end, are left out, so no total
is missing days. The history above starts on a Monday and ends on a Sunday,
so it makes exactly two weeks.

## Per city, per week

Time combines with the other levels of a selector. Add an identifier level to
get one weekly series per city:

```json
"selector": { "city": "any", "weekly": "any" }
```

Leave time out of the selector and the forecast stays at the time column's
own frequency — daily here.

## Only part of the history

A range keeps the weeks inside it and drops the rest:

```json
"selector": { "weekly": { "from": "2024-04-01" } }
```

## Your own time levels

The default levels cover most calendars. Declare others under the time
column's `partitions`, keyed by the name you'll use in `selector`:

```json
"date": {
  "kind": "time",
  "frequency": "daily",
  "partitions": {
    "fortnightly": { "interval": "2w", "anchor": "2024-01-01" },
    "weekly":      { "anchor": "sunday" }
  }
}
```

`fortnightly` is a new level of two-week periods starting on 1 January 2024.
`weekly` replaces the default weekly level with weeks starting on Sunday.
An anchor names where the periods start: a date, or a weekday for weekly
periods.

## What comes back

The same shape as any forecast, one row per week: `time` is the Monday each
week starts on, and `span` is `P7D`. `lead_time` counts up a week per row:
`PT0S`, `P7D`, `P14D`, `P21D`.