Référence de l’API

Create a forecast

Forecast the next bars of a candle series.

POST/v1/forecast

By default, the response is one series of candles: the central scenario. Set output to "distribution" to get the mean, the quantiles and the sample paths instead.

Headers

AuthorizationstringRequired: Bearer followed by your API key.
Content-TypestringRequired: application/json

Request body

modelstringRequired: The model to use, such as stochio-small-1. See GET /v1/models for the available models and their limits.
timestampsarray of stringRequired: One ISO 8601 timestamp per bar, strictly increasing: 2026-09-01, 2026-09-01T09:30:00 or 2026-09-01T09:30:00Z. Time zones are kept, since the model reads calendar features.
closearray of numberRequired: Closing prices, from 32 to 4,096 bars. Prices must be positive.
open, high, lowarray of numberOptional: Opening, high and low prices: all three or none, with low ≤ open, close ≤ high. Without them, the forecast is coarser. Defaults to close.
volumearray of numberOptional: Traded volume, zero or positive, one value per bar. Send it to get a meaningful volume forecast: without it, the forecast volume is close to zero.
amountarray of numberOptional: Traded amount, zero or positive, one value per bar.
contextnumberOptional: Number of most recent bars the model reads, from 32 to 512. Longer histories are truncated. Defaults to 512.
horizonnumberOptional: Number of bars to forecast, spaced like the history: from 1 to 48 (24 on the Developer plan), the horizon the model is trained and optimized for. Provide either horizon or future_timestamps.
future_timestampsarray of stringOptional: Exact timestamps to forecast, at most 48 (24 on the Developer plan), strictly increasing and after the history, such as the next trading sessions. Use instead of horizon.
output"candles" or "distribution"Optional: Response format. "candles" returns the central scenario as one series of candles. "distribution" returns the mean, the quantiles and, on request, the sample paths. Defaults to "candles".
sample_countnumberOptional: Number of sample paths to draw, from 1 to 256 (64 on the Developer plan). More paths give steadier quantiles and a steadier central scenario; output points grow in proportion. Defaults to 16.
seednumberOptional: Random seed, from 0 to 4,294,967,295. The same request with the same seed returns the same forecast; another seed draws other paths. Defaults to the server’s fixed seed.
mean_shrinknumberOptional: Share of the model’s trend the forecast keeps, from 0 (anchored to the last close) to 1 (raw model output). Defaults to the model’s default_mean_shrink.
quantilesarray of numberOptional: Only with "output": "distribution". From 1 to 9 levels, strictly between 0 and 1. Defaults to [0.1, 0.5, 0.9].
return_samplesbooleanOptional: Only with "output": "distribution". Also returns the sample paths. Defaults to false.
temperaturenumberOptional: Sampling temperature, in (0, 10]. Higher values widen the forecast range. Defaults to the server setting.
top_pnumberOptional: Nucleus sampling, in (0, 1]. Lower values restrict draws to the most likely values. Defaults to the server setting.
top_knumberOptional: Keeps only the k most likely values at each step, from 0 (disabled) to 1,024. Defaults to the server setting.

Returns

Candles (default)

idstring: Unique forecast identifier.
modelstring: The model that produced the forecast.
candlesarray of object: One candle per forecast bar, with timestamp, open, high, low, close and volume.
usageobject: input_points and output_points counted for the request, and cost, their price in euros at the plan’s pay-as-you-go rate (0 on the Developer plan).
latency_msnumber: Forecast duration, in milliseconds.

The candles are the central scenario: among the sample paths, the one whose closes best track their median, recentred with mean_shrink. Highs and lows always contain the open and the close. It is a plausible future, not an average or a promise.

Distribution

With "output": "distribution":

timestampsarray of string: The forecast timestamps.
meanobject: Mean of the sample paths for each column (open, high, low, close, volume, amount), one value per bar.
quantilesobject: For each requested level ("0.1", "0.5"…), one array per column, one value per bar.
samplesarray: With return_samples only. For each sample path, one row [open, high, low, close, volume, amount] per bar.
id, model, usage, latency_ms: As in the candles response.

Errors

Status	Error	Description
400	`invalid_request`	The request is malformed or exceeds a limit of your plan. The message names the field or the limit.
401	`invalid_api_key`	The API key is missing, invalid, revoked or expired, or its organization is closed.
402	`quota_exceeded`	Your organization reached a Developer plan quota. resets_at and the Retry-After header tell when it resets.
429	`rate_limited`	Your organization hit a rate limit (requests or output points per minute). Retry after the number of seconds in the Retry-After header.
502	`inference_failed`	The model did not return a valid forecast. Retry; contact us if the error persists.
503	`inference_unavailable`	The model is temporarily overloaded or unavailable. Retry after the number of seconds in the Retry-After header.

Example

curl https://api.stochio.fr/v1/forecast \
  -H "Authorization: Bearer $STOCHIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

The request body, shortened: a real request carries every bar.

request.json

{
  "model": "stochio-small-1",
  "timestamps": ["2026-09-01", "2026-09-02", "..."],
  "open":   [101.20, 102.05, "..."],
  "high":   [102.40, 102.90, "..."],
  "low":    [100.85, 101.30, "..."],
  "close":  [102.10, 101.75, "..."],
  "volume": [18250, 16930, "..."],
  "horizon": 24
}

Response

{
  "id": "fc_...",
  "model": "stochio-small-1",
  "candles": [
    {"timestamp": "2026-10-06T00:00:00", "open": 104.32, "high": 105.10, "low": 103.95, "close": 104.88, "volume": 17410.6},
    "... one candle per forecast bar"
  ],
  "usage": {"input_points": 512, "output_points": 384, "cost": 0},
  "latency_ms": 284
}

Les prévisions de Stochio sont probabilistes et ne constituent pas un conseil en investissement.