Prédiction

Les exemples utilisent $SPAVIK_BASE_URL et $SPAVIK_API_KEY, définis dans Démarrer.

POST /v1/forecast

Prévoir une série temporelle (sans entraînement)

Facturé un crédit par pas d'horizon et par série : cinq séries sur 7 pas coûtent 35 crédits, en un appel comme en cinq. L'appel est refusé (402 CREDITS_EXHAUSTED) avant tout calcul quand horizon x séries dépasse ce qui reste.

Plusieurs séries (item_id) sont prévues indépendamment, chacune sur son seul historique : les grouper économise des allers-retours mais ne change ni le prix ni les valeurs, et une série n'apprend pas d'une autre.

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

TIP

Accepte Idempotency-Key : rejouer le même appel avec la même clé rend la réponse déjà calculée, sans nouveau débit.

Corps de la requête

Nom	Type		Description
target	string	requis
horizon	integer	facultatif	Nombre de pas futurs (alias : prediction_length).
data	object[]	requis	Les lignes de données, un objet par ligne.
timestamp	string	facultatif	Colonne d'horodatage (déduite si omise).
quantiles	number[]	facultatif
item_id	string	facultatif	Colonne qui distingue plusieurs séries. Chaque série est prévue sur son seul historique.
point_estimate	mean | median	facultatif	Statistique servie dans <target>_prediction (la moyenne par défaut).

Cette route accepte aussi multipart/form-data, pour téléverser un fichier plutôt que de sérialiser les lignes en JSON.

Réponses

Code	Description
200	Succès
400	Série ou horizon invalide (INVALID_INPUT : moins de dix points, pas irrégulier, cible illisible).
401	Authentification requise, ou jeton invalide.
402	Plus de prédictions : le volume mensuel et le solde sont épuisés.
403	Cet appelant n'est pas autorisé à faire cette action.
413	Corps de requête trop volumineux.
422	FORECAST_FAILED : le calcul lui-même a échoué.

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/forecast" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{
  "target": "ventes",
  "horizon": 7,
  "data": [
    {
      "date": "2026-07-01",
      "ventes": 100
    },
    {
      "date": "2026-07-02",
      "ventes": 112
    },
    {
      "date": "2026-07-03",
      "ventes": 118
    },
    {
      "date": "2026-07-04",
      "ventes": 121
    },
    {
      "date": "2026-07-05",
      "ventes": 130
    },
    {
      "date": "2026-07-06",
      "ventes": 84
    },
    {
      "date": "2026-07-07",
      "ventes": 72
    },
    {
      "date": "2026-07-08",
      "ventes": 105
    },
    {
      "date": "2026-07-09",
      "ventes": 117
    },
    {
      "date": "2026-07-10",
      "ventes": 123
    },
    {
      "date": "2026-07-11",
      "ventes": 126
    },
    {
      "date": "2026-07-12",
      "ventes": 135
    },
    {
      "date": "2026-07-13",
      "ventes": 89
    },
    {
      "date": "2026-07-14",
      "ventes": 77
    },
    {
      "date": "2026-07-15",
      "ventes": 110
    },
    {
      "date": "2026-07-16",
      "ventes": 122
    },
    {
      "date": "2026-07-17",
      "ventes": 128
    },
    {
      "date": "2026-07-18",
      "ventes": 131
    },
    {
      "date": "2026-07-19",
      "ventes": 140
    },
    {
      "date": "2026-07-20",
      "ventes": 94
    },
    {
      "date": "2026-07-21",
      "ventes": 82
    },
    {
      "date": "2026-07-22",
      "ventes": 115
    },
    {
      "date": "2026-07-23",
      "ventes": 127
    },
    {
      "date": "2026-07-24",
      "ventes": 133
    },
    {
      "date": "2026-07-25",
      "ventes": 136
    },
    {
      "date": "2026-07-26",
      "ventes": 145
    },
    {
      "date": "2026-07-27",
      "ventes": 99
    },
    {
      "date": "2026-07-28",
      "ventes": 87
    }
  ]
}'

POST /v1/forecast/backtest

Vérifier qu'une série se prête à la prévision

Ne crée rien, ne facture rien. Valide la série (longueur, pas régulier, horodatages en double, cible numérique) et, si elle tient, rejoue des fenêtres de l'historique pour noter ce que le moteur aurait prédit face à ce qui est arrivé.

verdict.level vaut usable ou no_signal, décidé sur le MASE face à la référence naïve, jamais sur le seuil fixe de 1. by_window dit si le modèle est régulier, ce qu'une moyenne cache.

Les valeurs prévues ne sortent jamais d'ici : la prévision est facturée, cette route est gratuite. Utilisez POST /v1/forecast pour les obtenir.

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Corps de la requête

Nom	Type		Description
target	string	requis
horizon	integer	facultatif	Nombre de pas futurs (alias : prediction_length).
data	object[]	requis	Les lignes de données, un objet par ligne.
timestamp	string	facultatif	Colonne d'horodatage (déduite si omise).
quantiles	number[]	facultatif
item_id	string	facultatif	Colonne qui distingue plusieurs séries. Chaque série est prévue sur son seul historique.
point_estimate	mean | median	facultatif	Statistique servie dans <target>_prediction (la moyenne par défaut).

Cette route accepte aussi multipart/form-data, pour téléverser un fichier plutôt que de sérialiser les lignes en JSON.

Réponses

Code	Description
200	Succès
400	Série illisible, cible ou horodatage manquant, ou horizon qui n'est pas un entier de 1 à 1000 (VALIDATION_ERROR).
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/forecast/backtest" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{
  "target": "ventes",
  "horizon": 7,
  "data": [
    {
      "date": "2026-07-01",
      "ventes": 100
    },
    {
      "date": "2026-07-02",
      "ventes": 112
    },
    {
      "date": "2026-07-03",
      "ventes": 118
    },
    {
      "date": "2026-07-04",
      "ventes": 121
    },
    {
      "date": "2026-07-05",
      "ventes": 130
    },
    {
      "date": "2026-07-06",
      "ventes": 84
    },
    {
      "date": "2026-07-07",
      "ventes": 72
    },
    {
      "date": "2026-07-08",
      "ventes": 105
    },
    {
      "date": "2026-07-09",
      "ventes": 117
    },
    {
      "date": "2026-07-10",
      "ventes": 123
    },
    {
      "date": "2026-07-11",
      "ventes": 126
    },
    {
      "date": "2026-07-12",
      "ventes": 135
    },
    {
      "date": "2026-07-13",
      "ventes": 89
    },
    {
      "date": "2026-07-14",
      "ventes": 77
    },
    {
      "date": "2026-07-15",
      "ventes": 110
    },
    {
      "date": "2026-07-16",
      "ventes": 122
    },
    {
      "date": "2026-07-17",
      "ventes": 128
    },
    {
      "date": "2026-07-18",
      "ventes": 131
    },
    {
      "date": "2026-07-19",
      "ventes": 140
    },
    {
      "date": "2026-07-20",
      "ventes": 94
    },
    {
      "date": "2026-07-21",
      "ventes": 82
    },
    {
      "date": "2026-07-22",
      "ventes": 115
    },
    {
      "date": "2026-07-23",
      "ventes": 127
    },
    {
      "date": "2026-07-24",
      "ventes": 133
    },
    {
      "date": "2026-07-25",
      "ventes": 136
    },
    {
      "date": "2026-07-26",
      "ventes": 145
    },
    {
      "date": "2026-07-27",
      "ventes": 99
    },
    {
      "date": "2026-07-28",
      "ventes": 87
    }
  ]
}'

POST /v1/models/{id}/predict

Scorer des lignes avec un modèle entraîné

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

TIP

Accepte Idempotency-Key : rejouer le même appel avec la même clé rend la réponse déjà calculée, sans nouveau débit.

Corps de la requête

Nom	Type		Description
rows	object[]	requis	Les lignes de données, un objet par ligne.

Cette route accepte aussi multipart/form-data, pour téléverser un fichier plutôt que de sérialiser les lignes en JSON.

Réponses

Code	Description
200	Succès
401	Authentification requise, ou jeton invalide.
402	Plus de prédictions : le volume mensuel et le solde sont épuisés.
403	Cet appelant n'est pas autorisé à faire cette action.
409	Modèle pas encore entraîné.
413	Corps de requête trop volumineux.

Exemple

curl -X POST "$SPAVIK_BASE_URL/v1/models/{id}/predict" \
  -H 'X-API-Key: sk-spv-api-...' \
  -H 'Content-Type: application/json' \
  -d '{
  "rows": [
    {
      "plan": "free",
      "seats": 2,
      "tickets_90d": 7
    }
  ]
}'

GET /v1/models/{id}/predictions

Historique des prédictions du modèle

Authentification : Clé d'usage (X-API-Key) ou session web (Authorization: Bearer)

Paramètres

Nom	Où	Type		Description
limit	query	integer	facultatif

Réponses

Code	Description
200	Succès
401	Authentification requise, ou jeton invalide.
403	Cet appelant n'est pas autorisé à faire cette action.
503	PREDICTION_HISTORY_UNAVAILABLE : le journal (BigQuery) n'a pas pu être lu.

Exemple

curl -X GET "$SPAVIK_BASE_URL/v1/models/{id}/predictions" \
  -H 'X-API-Key: sk-spv-api-...'