POST /api/v1/forecasts

Starts an async forecast job. Returns 202 Accepted with job_id (UUID) and poll_url.

Attribute	Details
Auth	Required
Validate errors	422 — one validation detail (field + message) per response (fail-fast)
Malformed JSON	400
Body size	413 when the request body exceeds the body limit (currently 2 MiB)

Before charging: rate limits, concurrent-job cap, and the user's available balance for the hold may return 429 or 402 — see Errors & limits. Balances on GET /api/v1/me (available_eur_cents, balance_eur_cents) are in EUR cents.

Request body (pipeline v1)

Required top-level fields: pipeline_version, horizon, frequency, recency_factor, timeseries_metadata, timeseries. Optional: backtest, strictly_positive, filters.

pipeline_version

Must be exactly "v1" (case-sensitive). No "latest" alias.

horizon

Integer 1–12 inclusive.

frequency

Only "monthly" is supported in v1. "daily" / "weekly" return a clear not supported error; other values return unknown frequency.

backtest

Boolean. Type errors surface as 400 from JSON decoding before validation.

strictly_positive

Boolean, optional, defaults to false. Type errors surface as 400 from JSON decoding before validation.

When true, the request must satisfy two halves of the same contract:

• Input rule (validator): every value in timeseries must be >= 0 (zero is allowed). A single negative observation rejects the request with 422, fail-fast — only the first offending key is reported, with field timeseries["YYYY-MM-DD"] and a message naming the value and the flag.
• Output behavior (pipeline): the forecasting pipeline clamps the produced forecast at zero so no output point can be negative.

When false (or omitted) neither the input rule nor the output clamp is applied; negative observations are accepted and negative forecast points are returned unchanged.

recency_factor

Number 0.0–1.0 inclusive.

timeseries_metadata

Field	Rules
title	Required string, byte length ≥ 20 and ≤ 511 (not trimmed).
description	Optional; if present, ≤ 2048 bytes.
keywords	Optional array; if present, ≤ 20 items; each non-empty, each ≤ 255 bytes.

filters (optional, top-level)

If omitted or null, the whole object is ignored. When present:

• categories[] / regions[]: integer dimension ids — see Regions & categories for valid ids. The API does not cross-check them on submit.
• limit: optional integer 0–1000. Has no direct effect on forecast billing;

timeseries

Object mapping YYYY-MM-DD keys → finite numbers.

1. Must be non-empty.
2. Values must be finite (no NaN/Inf).
3. Keys must be valid calendar dates; for monthly frequency, keys must be aligned (e.g. first day of month — see API error text).
4. Series must have no gaps in the monthly grid (first issue wins).
5. Minimum length depends on horizon (monthly points):

Horizon	Minimum monthly points
1–3	40
4–6	60
7–12	120

6. Recency: the latest observation must be within the past 12 months (UTC-relative comparison in the validator).

7. Intermittent demand: if the series is classified intermittent (ADI ≥ 1.32, computed as total_periods / non_zero_periods), extra rules apply:

   • At least 60 monthly points.
   • At least 20% non-zero values (max intermittency 0.8).
   • horizon restricted to 3 or 6 only.
   • Zero detection uses strict equality: small positive floors (e.g. 1e-6 substituted for true zeros) count as non-zero and may bypass this classification.

Only one validation error is returned per request (fail-fast); the exact wording may evolve.

Success response (202)

Includes job_id (UUID string). Poll GET /api/v1/forecasts/:id with that id.

Related

• GET forecast status
• Artifacts
• POST /api/v1/drivers — accepts the same filters object
• Regions & categories — browse valid dimension ids
• Errors & limits