Prediction

Examples use $SPAVIK_BASE_URL and $SPAVIK_API_KEY, set in Get started.

POST /v1/forecast

Forecast a time series (zero-shot)

Billed one credit per horizon step per series: five series over 7 steps cost 35 credits, in one call or in five. The call is refused (402 CREDITS_EXHAUSTED) before any computation when horizon x series exceeds what is left.

Several series (item_id) are forecast independently, each from its own history only: grouping them saves round trips but changes neither the price nor the values, and one series does not learn from another.

Authentication : API key (X-API-Key) or web session (Authorization: Bearer)

TIP

Accepts Idempotency-Key: replaying the same call with the same key returns the already computed response, with no second charge.

Request body

Name	Type		Description
target	string	required
horizon	integer	optional	Number of future steps (alias: prediction_length).
data	object[]	required	Data rows, one object per row.
timestamp	string	optional	Timestamp column (inferred when omitted).
quantiles	number[]	optional
item_id	string	optional	Column identifying several series. Each series is forecast on its own history only.
point_estimate	mean | median	optional	Statistic served in <target>_prediction (defaults to mean).

This route also accepts multipart/form-data, to upload a file instead of serialising rows as JSON.

Responses

Code	Description
200	Success
400	Invalid series or horizon (INVALID_INPUT: fewer than ten points, irregular interval, unreadable target).
401	Authentication required, or invalid token.
402	Out of predictions: monthly allowance and balance are both empty.
403	This caller is not allowed to perform this action.
413	Payload too large.
422	FORECAST_FAILED: the computation itself failed.

Example

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

Check whether a series can be forecast at all

Creates nothing, charges nothing. Validates the series (length, regular interval, duplicate timestamps, numeric target) and, if it holds, replays windows of the history to score what the engine would have predicted against what happened.

verdict.level is usable or no_signal, decided on the MASE against the naive baseline, never against the fixed threshold of 1. by_window says whether the model is consistent, which an average hides.

The forecast values are never returned here: forecasting is billed, this route is free. Use POST /v1/forecast to get them.

Authentication : API key (X-API-Key) or web session (Authorization: Bearer)

Request body

Name	Type		Description
target	string	required
horizon	integer	optional	Number of future steps (alias: prediction_length).
data	object[]	required	Data rows, one object per row.
timestamp	string	optional	Timestamp column (inferred when omitted).
quantiles	number[]	optional
item_id	string	optional	Column identifying several series. Each series is forecast on its own history only.
point_estimate	mean | median	optional	Statistic served in <target>_prediction (defaults to mean).

This route also accepts multipart/form-data, to upload a file instead of serialising rows as JSON.

Responses

Code	Description
200	Success
400	Series unreadable, target or timestamp missing, or horizon not an integer from 1 to 1000 (VALIDATION_ERROR).
401	Authentication required, or invalid token.
403	This caller is not allowed to perform this action.

Example

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

Score rows with a trained model

Authentication : API key (X-API-Key) or web session (Authorization: Bearer)

TIP

Accepts Idempotency-Key: replaying the same call with the same key returns the already computed response, with no second charge.

Request body

Name	Type		Description
rows	object[]	required	Data rows, one object per row.

This route also accepts multipart/form-data, to upload a file instead of serialising rows as JSON.

Responses

Code	Description
200	Success
401	Authentication required, or invalid token.
402	Out of predictions: monthly allowance and balance are both empty.
403	This caller is not allowed to perform this action.
409	Model not trained yet.
413	Payload too large.

Example

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

Prediction history of the model

Authentication : API key (X-API-Key) or web session (Authorization: Bearer)

Parameters

Name	In	Type		Description
limit	query	integer	optional

Responses

Code	Description
200	Success
401	Authentication required, or invalid token.
403	This caller is not allowed to perform this action.
503	PREDICTION_HISTORY_UNAVAILABLE: the log (BigQuery) could not be read.

Example

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