POST /v1/forecast

POST https://api.sequenxai.com/v1/forecast forecasts the history of one or more entities online. The server first cleans the data under the effective cleaning policy (the raw preset only checks its structure), then runs the selected model, and finally maps the forecast back onto timestamps. Authentication is described in Authentication & Headers.

1. Request examples

export SEQUENX_API_KEY="sqx_live_..."   # created at https://platform.sequenxai.com

# 96 points at 15-minute steps, h=24, level=[80, 90], model hora-1.0
curl -sSO https://docs.sequenxai.com/data/power-grid-15m.json

curl -sS -X POST "https://api.sequenxai.com/v1/forecast" \
  -H "Authorization: Bearer $SEQUENX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: quickstart-0001" \
  -d @power-grid-15m.json

import math
import os

import requests

API_URL = "https://api.sequenxai.com/v1/forecast"
API_KEY = os.environ["SEQUENX_API_KEY"]

# 48 hourly observations of one meter.
series = [
    {
        "unique_id": "meter-001",
        "ds": f"2026-09-{1 + i // 24:02d}T{i % 24:02d}:00:00Z",
        "y": round(140 + 8 * math.sin(2 * math.pi * i / 24), 1),
    }
    for i in range(48)
]

resp = requests.post(
    API_URL,
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"model": "hora-1.0", "series": series, "h": 24, "freq": "1h", "level": [80, 90]},
    timeout=180,
)
body = resp.json()
if resp.status_code != 200:
    error = body["error"]
    raise SystemExit(f"{resp.status_code} {error['code']}: {error['message']} ({error['request_id']})")

print(body["request_id"], body["effective_policy"]["id"], body["usage"])
for row in body["forecast"][:3]:
    print(row["ds"], row["y_hat"], row["intervals"]["80"])

// Node.js 18+ (global fetch). Call from your server; never ship the key to a browser.
const API_URL = "https://api.sequenxai.com/v1/forecast";

// 48 hourly observations of one meter.
const series = Array.from({ length: 48 }, (_, i) => ({
  unique_id: "meter-001",
  ds: new Date(Date.UTC(2026, 8, 1, i)).toISOString().replace(".000Z", "Z"),
  y: Math.round((140 + 8 * Math.sin((2 * Math.PI * i) / 24)) * 10) / 10,
}));

const resp = await fetch(API_URL, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SEQUENX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ model: "hora-1.0", series, h: 24, freq: "1h", level: [80, 90] }),
  signal: AbortSignal.timeout(180_000),
});
const body = await resp.json();
if (!resp.ok) {
  const { code, message, request_id } = body.error;
  throw new Error(`${resp.status} ${code}: ${message} (${request_id})`);
}

console.log(body.request_id, body.effective_policy.id, body.usage);
for (const row of body.forecast.slice(0, 3)) {
  console.log(row.ds, row.y_hat, row.intervals["80"]);
}

2. Request body

Fields outside the contract at the top level or inside options.cleaning return 422 VALIDATION_ERROR (details.errors[].field names the field, e.g. options.cleaning.imputer) and are never silently ignored; unknown keys directly under options are still ignored. Presets, accept and decline are explained in Cleaning Presets & Report.

3. Validation order

The server handles a request in this order; a failed check stops the request before later steps. No non-200 response is billed.

1. Authentication and scope: 401 INVALID_API_KEY, 403 INSUFFICIENT_SCOPE. Then the account checks: 503 SERVICE_UNAVAILABLE with Retry-After while SequenxAI has paused the endpoint, 403 ACCOUNT_SUSPENDED, 403 ORG_PENDING_DELETION. Then Idempotency-Key, when sent: 400 VALIDATION_ERROR for a malformed key, 422 IDEMPOTENCY_KEY_REUSED, 409 IDEMPOTENCY_IN_PROGRESS; an identical retry of a finished request returns the stored result here, without counting toward the per-minute limit.
2. Requests per minute per account (shared by all its keys): 429 with X-RateLimit-Policy: forecast-rpm. Rate-limited calls are not recorded.
3. Body parsing and field validation: 400 MALFORMED_JSON, 422 VALIDATION_ERROR (including more than 8 covariate columns), FUTURE_COVARIATES_INVALID, COVARIATE_COLUMN_MISMATCH.
4. Row cap (series plus future_covariates): 422 POINTS_EXCEEDED.
5. Cleaning preset: 422 CLEANING_OPTION_UNSUPPORTED; raw without freq returns 422 VALIDATION_ERROR.
6. Model: any id other than hora-1.0 / hora returns 422 MODEL_NOT_AVAILABLE, a model_options key the model does not take returns 422 MODEL_OPTION_UNSUPPORTED, temporarily unavailable returns 503 SERVICE_UNAVAILABLE; h above the model's limit returns 422 HORIZON_EXCEEDS_MODEL; with quantile_policy: strict, a non-native quantile (including point_quantile) returns 422 QUANTILE_UNSUPPORTED; an entity with more distinct timestamps (rows under raw) than the model's maximum context returns 422 SERIES_TOO_LONG.
7. Daily point quota: reserves "rows + h × entities"; if that does not fit, 429 with X-RateLimit-Policy: forecast-daily-points.
8. Cleaning (or the raw structural check): the 422 cleaning codes, RAW_INPUT_INVALID, SERIES_TOO_SHORT, and SERIES_TOO_LONG when the cleaned grid (filled slots included) is longer than the model's maximum context.
9. Inference: 503 MODEL_BUSY, 504 GATEWAY_TIMEOUT, 503 SERVICE_UNAVAILABLE.
10. Success: settles on the observed and forecast points the model actually handled and returns the rest of the reservation.

4. Response fields

5. Response example

Numbers are illustrative and cleaning_report is abridged:

{
  "request_id": "req_4f1c8e2a9b7d4e0c8a3f5b6d7e8f9a0b",
  "model_used": "hora-1.0",
  "freq": "1h",
  "forecast": [
    {
      "unique_id": "meter-001",
      "ds": "2026-09-03T00:00:00Z",
      "y_hat": 140.6,
      "intervals": {
        "80": {"lo": 137.9, "hi": 143.2},
        "90": {"lo": 136.4, "hi": 144.8}
      }
    }
  ],
  "data_quality": {
    "status": "ok",
    "inferred_freq": null,
    "missing_ratio": 0.0,
    "imputed_points": 0,
    "outlier_points_suppressed": 0,
    "timezone_normalized": true,
    "notes": []
  },
  "usage": {
    "series_count": 1,
    "input_data_points": 48,
    "forecast_data_points": 24,
    "latency_ms": 812
  },
  "effective_policy": {
    "id": "default@2026-13",
    "preset": "default",
    "version": "2026-13",
    "source": "platform"
  },
  "model_input": [
    {
      "unique_id": "meter-001",
      "context_points": 48,
      "fed_points": 48,
      "truncated": 0,
      "missing_mode": "filled",
      "covariates_used": false
    }
  ],
  "quantile_report": {
    "policy": "nearest",
    "requested": [0.05, 0.1, 0.5, 0.9, 0.95],
    "used": [0.05, 0.1, 0.5, 0.9, 0.95],
    "substitutions": []
  },
  "cleaning_report": {
    "schema_version": "cleaning_report/1",
    "policy": {"id": "default@2026-13", "...": "..."},
    "overall": {"series_count": 1, "input_points": 48, "output_points": 48, "...": "..."},
    "series": ["..."],
    "warnings": [],
    "blocking": [],
    "decisions": []
  }
}

6. The raw preset

options.cleaning.preset: "raw" skips cleaning and only runs a structural check before the model. Use it for data you already clean in your own systems. Requirements:

• freq is required and must be a fixed step (s, min, h, D, W and multiples); calendar frequencies such as MS or M@15 are not supported.
• Every ds is exactly YYYY-MM-DDTHH:MM[:SS[.ffffff]] followed by Z or ±HH:MM; no other format is accepted.
• Each entity's rows are strictly increasing in time, one freq step apart; nothing is sorted, de-duplicated or filled.
• Every y is a finite number, never null.
• It cannot be combined with accept / decline or cleaning parameters such as impute_method (422 CLEANING_OPTION_UNSUPPORTED).

Otherwise the call returns 422 RAW_INPUT_INVALID. details.violations lists up to 20 problems, each with unique_id, index and reason, where reason is one of freq_invalid, calendar_freq_unsupported, ds_format, ds_duplicate, ds_not_increasing, step_mismatch, not_observed:

{
"error": {
  "code": "RAW_INPUT_INVALID",
  "message": "Raw input is not a regular, finite series",
  "request_id": "req_…",
  "details": {
    "violations": [
      {"unique_id": "meter-001", "index": 5, "reason": "step_mismatch"}
    ],
    "hint": "Use the default cleaning preset, or call /v1/clean to see the cleaning report."
  }
}
}

Raw responses carry no cleaning_report, and data_quality is always {"status": "ok", "missing_ratio": 0.0}. Under raw the row count of each entity is checked against the model's maximum context before anything runs (SERIES_TOO_LONG); nothing is cut.