# Get the forecast as parquet

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

Every request on these pages comes back as JSON. That's the default; the
`Accept` header picks another format. Parquet is the one to reach for when the
forecast goes straight into a dataframe, a warehouse or a lake: the same table,
typed and compressed, with nothing to parse.

This request forecasts a week of sales per city from the sample data:

```json
{
  "input": {
    "source": {
      "uri": "https://tfc-docs-examples-eu-central-1.s3.eu-central-1.amazonaws.com/retail/v1/sales.parquet"
    },
    "columns": {
      "date":  { "kind": "time", "frequency": "1d" },
      "store": "identifier",
      "city":  "identifier",
      "sales": { "kind": "target", "aggregate": "sum" }
    },
    "hierarchies": {
      "store": [["store", "city"]]
    }
  },
  "selector": { "city": "any" },
  "prediction_length": "1w",
  "quantiles": [0.1, 0.5, 0.9]
}
```

<RunExample example="response-formats" accept="application/vnd.apache.parquet" />

Ask for parquet with the `Accept` header:

```bash
curl -X POST "https://api.retrocast.com/v1/forecast?model=t0-gamma" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/vnd.apache.parquet" \
  -d @request.json \
  -o forecast.parquet
```

The button above sends the same header, and the playground shows the file as a
table.

## The formats

| `Accept` | What comes back |
| --- | --- |
| `application/json` (default) | One object, `data`, holding the table as one array per column. |
| `application/vnd.apache.parquet` | The same table as a parquet file, one row per (series, time step). |
| `application/x-ndjson` | One JSON record per series, one per line. |
| `application/vnd.msgpack` | The same records as NDJSON, in MessagePack. |
| `application/x-tar` | A tar archive of the parquet forecast and the input the model read. |

Anything else is rejected with `406 Not Acceptable`, naming the formats above.

## Parquet

One row per city and day, so 14 rows here. The columns are the ones the JSON
response carries in `data`: `time` and `cutoff` as UTC timestamps, `lead_time`
and `span` as ISO 8601 durations, then `identifiers` and `targets` as nested
structs, and `auxiliary`, empty for these requests. The first two rows, with
the quantiles rounded here:

| time | cutoff | lead_time | span | identifiers | targets |
| --- | --- | --- | --- | --- | --- |
| 2024-12-30 | 2024-12-29 | `PT0S` | `P1D` | `{"city":"Lyon"}` | `{"sales":{"quantiles":{"0.1":51.63,"0.5":63.59,"0.9":74.74}}}` |
| 2024-12-31 | 2024-12-29 | `P1D` | `P1D` | `{"city":"Lyon"}` | `{"sales":{"quantiles":{"0.1":44.91,"0.5":56.02,"0.9":67.04}}}` |

Read it with any parquet reader — `pandas.read_parquet`, `polars.read_parquet`,
DuckDB's `read_parquet` — and flatten the structs there if you want one column
per quantile.

## NDJSON and MessagePack

One record per series instead of one row per step: each target's quantiles
are arrays, one value per step. Trimmed to the first step:

```json
{
  "identifiers": { "city": "Lyon" },
  "cutoff": "2024-12-29T00:00:00Z",
  "origin": "2024-01-01T00:00:00Z",
  "first_step": 364,
  "lead_time": "PT0S",
  "frequency": "P1D",
  "span": "P1D",
  "targets": {
    "sales": {
      "quantiles": { "0.1": [51.62795], "0.5": [63.592873], "0.9": [74.73698] }
    }
  }
}
```

Times are written as steps from `origin`: the first forecast step is `origin`
plus `first_step` steps of `frequency` — here 2024-01-01 plus 364 days,
30 December.

The last line is not a series. It reports what the request used:

```json
{ "usage": { "forecast_units": 2, "timestamp": 1795013473, "formula": "target-cutoff-v1" } }
```

## The forecast and its input

`application/x-tar` returns two parquet files:

- `forecast.parquet` — the same file the parquet format returns.
- `materialization.parquet` — the input rows as the model read them, after
  selection and roll-ups. Here that's one row per city and day — 728 rows —
  with each city's stores already summed:

| city | date | sales |
| --- | --- | --- |
| Lyon | 2024-01-01 | 46 |
| Lyon | 2024-01-02 | 51 |

That's the series the model forecast from, so it's what to plot the forecast
against, or what to check when a number looks off.
