Copy page

Cookbook

Send a parquet file

Inline rows travel inside the JSON body, which is fine for a few hundred rows and wasteful for a real table. Upload the file instead: send the request as multipart/form-data, with the query in a part named query and the data in a part of its own.

This is the one case where the request isn't plain JSON, so here is the whole curl call:

Code
curl -X POST "https://api.retrocast.com/v1-beta/forecast?model=t0-alpha" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected];type=application/json" \
  -F "[email protected]"

query.json is the same request body you would have posted as JSON, except that source points at the uploaded part with a uri instead of carrying rows:

Code
{
  "input": {
    "source": { "uri": "inline://sales" },
    "columns": {
      "date":  { "kind": "time", "frequency": "1d" },
      "store": "identifier",
      "sales": { "kind": "target", "aggregate": "sum" }
    }
  },
  "prediction_length": "2w"
}

model names the forecasting model and is required on every call to this endpoint.

The part name is yours to choose. inline://sales means the part sent as -F "[email protected]" — the name in the URL is the part name, not a file name, so inline://sales.parquet would not resolve.

Two errors tell you the two halves are out of step: the query reads inline://x, but no part was uploaded under that name, and part x is not read by the query.

One part per source

A uri names a single part; it does not take a list. To forecast several files as one table, concatenate them before uploading.

Several parts are for several sources. A covariate has a source of its own, so it can come from its own part:

Code
curl -X POST "https://api.retrocast.com/v1-beta/forecast?model=t0-alpha" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected];type=application/json" \
  -F "[email protected]" \
  -F "[email protected]"

Code
"covariates": [
  {
    "schema": {
      "version": "0.3",
      "source": { "uri": "inline://weather" },
      "columns": {
        "date":        { "kind": "time", "frequency": "1d" },
        "temperature": "historical"
      }
    },
    "on": [{ "base": "date", "attached": "date" }]
  }
]

Parts can be Parquet or Arrow IPC files. Write Arrow uncompressed — an LZ4-compressed Arrow file is rejected with lz4 IPC decompression requires the lz4 feature.

What comes back

The same response as any other request. One row per (store, time step), since store is an identifier and nothing aggregates it away:

Code
{
  "data": {
    "time":      ["2024-02-10T00:00:00Z", "2024-02-11T00:00:00Z"],
    "cutoff":    ["2024-02-09T00:00:00Z", "2024-02-09T00:00:00Z"],
    "lead_time": ["PT0S", "P1D"],
    "span":      ["P1D", "P1D"],
    "identifiers": { "store": ["S1", "S1"] },
    "targets": {
      "sales": {
        "quantiles": {
          "0.1":  [143.5, 144.1],
          "0.5":  [144.8, 145.7],
          "0.9":  [145.8, 146.7],
          "mean": [144.7, 145.6]
        }
      }
    }
  }
}

It is JSON either way — uploading a file changes how the input arrives, not how the forecast comes back.