Forecast time series
POST /v1/forecast
apiKeyX-Spavik-Api-Key<token>Spavik integration API key (sk-spv-api-...), sent in X-Spavik-Api-Key.
Idempotency-Key?stringSame workspace, method, path, key and payload prevent another execution or charge, subject to current model access. Successful responses are replayed for every data policy, including ZDR, from the technical PostgreSQL cache (default retention 24 hours from operation creation). The data policy only controls inference input/output archiving to GCS/BigQuery; it never changes replay behavior. A different key or an expired completed key starts a new operation and may be charged again. REQUEST_IN_PROGRESS: wait Retry-After. REQUEST_INTERRUPTED: outcome uncertain; contact support. IDEMPOTENCY_RESPONSE_UNAVAILABLE: a completed response is missing; do not retry with a new key. Completed keys expire; unresolved keys remain protected. Reusing a key with different input returns 422. A key is required on the original call for safe retries.
User-Agent?stringInformation about the agent originating the request, when known. Browsers supply their own value. Optional diagnostic metadata, declared by the caller and never used for authorization. Omit unknown values. Values are trimmed and truncated to the documented length.
length <= 1024X-Spavik-Client-Name?stringHTTP caller: SDK, MCP server or direct application (for example spavik-sdk-python, spavik-sdk-javascript or spavik-mcp). Optional diagnostic metadata, declared by the caller and never used for authorization. Omit unknown values. Values are trimmed and truncated to the documented length.
length <= 128X-Spavik-Client-Version?stringVersion of that SDK, MCP server or direct application. Optional diagnostic metadata, declared by the caller and never used for authorization. Omit unknown values. Values are trimmed and truncated to the documented length.
length <= 64- body
engine_family?stringEngine family for this call. Omitted: the family marked is_default in GET /v1/engine-families. No persisted model is used. engine_version must belong to this family, including when the family is omitted.
"flair""presage""prophecy"engine_version?stringFull engine identifier within the selected family, e.g. presage-2 or presage-latest. Omitted or -latest: latest active version of that family. A different family is refused. Responses identify the exact version used.
^(flair|presage|prophecy)-(latest|[1-9][0-9]*(\.[0-9]+)?)$length <= 64backtest?booleanEvaluate historical windows on POST /v1/forecast. The dedicated backtest route always evaluates.
falseinclude_backtest_predictions?booleanReturn the historical observations already evaluated by the backtest, without additional inference or credits. On POST /v1/forecast, also set backtest=true. Does not force a skipped or disabled backtest to run. Detail is always JSON.
falsetarget*stringhorizon?integerNumber of future steps (alias: prediction_length).
1 <= value <= 1000data*array<>Data rows, one object per row.
timestamp?stringTimestamp column (inferred when omitted).
quantiles?array<number>item_id?stringColumn identifying several series. Each series is forecast on its own history only.
point_estimate?stringStatistic served in _prediction (defaults to mean).
"mean""median"Success
application/json- response
forecast_csv?stringtarget?stringprediction_length?integern_series?integern_context?integerpoint_estimate?stringStatistic served in the _prediction column. With median it matches quantile_0.5 exactly; with mean it differs on a skewed distribution.
"mean""median"metrics?Scores on evaluated observations. Classification: AUC, Accuracy, AveragePrecision (binary only), LogLoss and MacroF1. Regression: MAE, RMSE, R². Forecasting adds MASE, Bias, BiasRatio and Pinball. Undefined scores are null; see metric_context.undefined_reasons. Secondary scores do not change the primary assessment.
baselines?Naive baselines (seasonal when selected from the initial training context) measured on the same evaluated points as metrics. MASE also includes constant_floor and constant_label for the historical median estimated before each window. Model, naive and constant share the same scale computed before the earliest evaluation window. Compare MASE to these scores, never to the fixed threshold of 1.
seasonal_period?integerbacktest?Score per origin: mase_by_window gives the MASE of each window, naive_mase_by_window and constant_mase_by_window the matching baseline scores. Window indices are relative to each series end and may represent different dates. Protocol v2 MASE weights eligible series equally, then points within each series. Other metrics weight points equally. Do not reconstruct the aggregate by averaging window scores.
backtest_skipped?stringSet when a requested backtest could not run (series too short).
intervals?Coverage and width on the same backtest observations, using the widest available quantile pair. Fractions use 0 to 1. Width is in target units, never an implicit percentage. Descriptive measurements do not establish calibration.
evaluation?warnings?array<string>engine?stringimport requestsurl = "https://api.spavik.co/v1/forecast"body = """{ "engine_family": "presage", "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 } ]}"""response = requests.request("POST", url, data = body, headers = { "Content-Type": "application/json"})print(response.text){ "forecast_csv": "string", "target": "string", "prediction_length": 0, "n_series": 0, "n_context": 0, "point_estimate": "mean", "metrics": { "AUC": 0, "Accuracy": 0, "AveragePrecision": 0, "LogLoss": 0, "MacroF1": 0, "MAE": 0, "RMSE": 0, "R²": 0, "MASE": 0, "Bias": 0, "BiasRatio": 0, "Pinball": 0, "property1": 0, "property2": 0 }, "baselines": {}, "seasonal_period": 0, "backtest": { "predictions": [ { "series": "string", "window": 0, "timestamp": "string", "actual": 0, "prediction": 0, "naive_prediction": 0, "constant_prediction": 0, "quantiles": { "property1": 0, "property2": 0 } } ] }, "backtest_skipped": "string", "intervals": { "nominal": 0, "observed": 0, "lower": 0, "upper": 0, "evaluated_count": 0, "average_width": 0, "width_unit": "target", "undefined_reason": "string" }, "evaluation": { "metric_context": { "undefined_reasons": { "property1": "string", "property2": "string" }, "class_order": [ "string" ], "positive_class": "string", "auc_average": "binary", "average_precision_method": "non_interpolated", "macro_f1_average": "unweighted_defined_classes", "log_loss_epsilon": 0 } }, "warnings": [ "string" ], "engine": "string"}How is this guide?
Last updated on