Forecasts and sessions over the API

How to upload sales, train and wait for the result, and read a session's forecasts, accuracy and results.

A session is one forecast run: some sales, a configuration and the result of training it. The app works with the active session, the one GET /planning returns in active_session_id. Sessions are never deleted: DELETE /sessions/{id} archives them and POST /sessions/{id}/restore brings them back.

The complete nightly cycle

This is the work most integrations need: replace the sales file, retrain and wait.

#!/usr/bin/env bash
set -euo pipefail
API=https://app.stockai.es/api/v1
AUTH="Authorization: Bearer $STOCKAI_KEY"

# 1. Replace the sales file in place (same source id, same column mapping)
curl -sf -X POST "$API/data-sources/$SOURCE_ID/file" -H "$AUTH" -F "file=@/exports/sales.csv"

# 2. Which session is active right now (ask every time, never hard-code it)
SESSION=$(curl -sf "$API/planning" -H "$AUTH" | jq -r '.data.active_session_id')

# 3. Retrain (skip this if the session has a schedule: it retrains when the file changes)
curl -sf -X POST "$API/sessions/$SESSION/train" -H "$AUTH" \
     -H "Content-Type: application/json" -d '{}'

# 4. Wait while it is QUEUED or RUNNING. Watching only RUNNING exits on the first pass.
while :; do
  ST=$(curl -sf "$API/sessions/$SESSION/train/status" -H "$AUTH" | jq -r '.data.status')
  case "$ST" in QUEUED|RUNNING) sleep 10 ;; *) break ;; esac
done
echo "Training finished: $ST"

1. Look up your sales source's id once with GET /data-sources (or GET /datasets) and keep it in your configuration: that id does not change.
2. Every night replace the file with POST /data-sources/{id}/file (multipart, field file). The source keeps its id and its column mapping. It accepts .csv, .xlsx, .xls, .parquet and .json.
3. Ask for the active session with GET /planning.
4. If the session has a schedule, StockAI retrains on its own when the file changes and you can skip this step. Otherwise queue training with POST /sessions/{id}/train.
5. Poll GET /sessions/{id}/train/status every few seconds while it says QUEUED or RUNNING. It ends in COMPLETED or FAILED.

{
  "session_id": "sess_cc9ab9137953",
  "status": "RUNNING",
  "job_id": "job_fe6d1a76b4f2",
  "job": {
    "status": "RUNNING",
    "created_by": "usr_97c71ad04a86",
    "progress": { "step": "ml_training", "message": "Training ML models", "percent": 27 },
    "error": null
  }
}

Data sources and datasets

Sessions and configuration

Retraining on a schedule

curl -X POST https://app.stockai.es/api/v1/sessions/$SESSION/schedule \
  -H "Authorization: Bearer $STOCKAI_KEY" -H "Content-Type: application/json" \
  -d '{"cron_expr":"0 6 * * 1","enabled":true}'

cron_expr is a cron expression (in the example: Mondays at 6:00). GET /schedules lists them all, GET /schedules/history their runs, and DELETE /sessions/{id}/schedule removes the schedule. It is the same as the "Schedules" tab under Automation.

Reading the forecast

curl "https://app.stockai.es/api/v1/sessions/$SESSION/forecast-series/SKU-001" \
  -H "Authorization: Bearer $STOCKAI_KEY"

# "data": {
#   "sku": "SKU-001", "model": "ets", "available_models": ["ets"],
#   "historical": [{ "date": "2024-01-01", "value": 25.0 }, ...],
#   "forecast":   [{ "date": "2025-04-01", "value": 40.67,
#                    "p10": 35.53, "p50": 40.67, "p90": 45.81,
#                    "lower": 34.07, "upper": 47.26 }, ...]
# }

Datasets for BI

For Power BI, Excel or Looker there are flat tables meant to be read whole: /datasets/forecast-points, /datasets/inventory-status, /datasets/accuracy, /datasets/purchase-order-lines, /datasets/receptions and /datasets/committed-demand; /datasets/schema describes their columns. They accept format, page, limit and session_id. Since many BI tools cannot set Authorization, use X-API-Key.

curl "https://app.stockai.es/api/v1/datasets/forecast-points?format=csv&page=1" \
  -H "X-API-Key: $STOCKAI_KEY" -o forecast-points.csv