v2

latestOpenAPI 3.0.32026-07-26112274.7 KB

Submit an async forecast job

Submits a monthly forecast job. The job runs asynchronously — poll GET /api/v1/forecasts/{id} until status is completed or failed. Output files are then available via GET /api/v1/forecasts/{id}/artifacts/{name}.

The timeseries must contain at least the horizon-dependent minimum number of monthly observations (40 for max horizon 1–3, 60 for 4–6, 120 for 7–12) aligned to the first of each month. At least one of soft_horizon or hard_horizon must be specified.

post/api/v1/forecasts

Request body

aux_timeseriesobject[]

Optional. One to ten auxiliary driver series. Each item is a map of the same YYYY-MM-DD date keys as timeseries — exactly the same dates, no more and no fewer — to numeric values. Each series becomes a forecast driver that is kept through feature selection, and series are identified by their array position (the first is aux_0, the second aux_1, and so on). When omitted, the forecast runs without auxiliary drivers.

backtestboolean

When true, run a backtest evaluation alongside the forecast and include backtest_metrics.json and backtest_trajectories.json in the artifacts.

frequency'monthly' required

Series cadence. Only monthly is currently supported.

hard_horizoninteger

Minimum acceptable horizon (months) for the quality step-down ladder. When omitted, the pipeline falls back to a driverless forecast at soft_horizon if no quality run succeeds. When still failing at hard_horizon, the pipeline emits a driverless forecast at that horizon. At least one of soft_horizon or hard_horizon must be present. When both are set, hard_horizon must be less than or equal to soft_horizon. Maximum 12.

max_num_featuresinteger

Optional. Caps the number of drivers kept by the final feature-selection step (top-k). When omitted, the pipeline uses the regime default. Bounded above by the regime's selector ceiling, so a value larger than that cap is a no-op. Must be a positive integer when present.

optimization_budget'none' | 'low' | 'mid' | 'high'

Optional. Tunes the number of hyper-parameter-optimization trials. low runs fewer trials, high runs the most; none and mid fall back to the pipeline default. Defaults to none.

pipeline_version'v1' required

Pipeline version. Closed set — only v1 is supported today.

recency_factornumber double required

Weight given to more recent observations when selecting drivers. 0.0 = equal weight across the full history; 1.0 = strongest recency bias.

run_baselineboolean

When true, re-run the same primary model with drivers stripped and surface its metrics as a self-comparison baseline alongside the reference baselines, isolating the lift the drivers add. Defaults to false.

soft_horizoninteger

Ideal forecast horizon (months). The pipeline tries this first, then steps down by one month until it reaches hard_horizon (when set) while seeking a quality forecast. At least one of soft_horizon or hard_horizon must be present. When both are set, hard_horizon must be less than or equal to soft_horizon. Maximum 12.

strictly_positiveboolean

When true, every value in timeseries must be >= 0; a single negative observation rejects the request with 422. The pipeline also clamps output values at zero. Defaults to false.

timeseriesobject required

Map of YYYY-MM-DD date keys to numeric observation values. Must contain at least the horizon-dependent minimum number of monthly observations (40 for max horizon 1–3, 60 for 4–6, 120 for 7–12) aligned to the first of each month.

trend_num_classes2 | 3

Optional. Trend-classification label granularity: 2 (binary up/down) or 3 (down/flat/up). Consumed only on the trend analysis path and ignored otherwise. When omitted, the pipeline applies its default of 3.

Example request

{
  "pipeline_version": "v1",
  "frequency": "monthly",
  "recency_factor": 0.6,
  "soft_horizon": 6,
  "hard_horizon": 3,
  "backtest": true,
  "timeseries_metadata": {
    "title": "Brent Crude Oil Price Monthly",
    "description": "Monthly average Brent crude oil spot price in USD/barrel, sourced from EIA.",
    "keywords": [
      "oil",
      "brent",
      "energy",
      "commodity"
    ]
  },
  "timeseries": {
    "2021-01-01": 57.64,
    "2021-02-01": 65.02,
    "2021-03-01": 67.24,
    "2021-04-01": 71.07,
    "2021-05-01": 70.25,
    "2021-06-01": 65.5,
    "2021-07-01": 64.25,
    "2021-08-01": 58.96,
    "2021-09-01": 62.01,
    "2021-10-01": 59.87,
    "2021-11-01": 63.43,
    "2021-12-01": 66.52,
    "2022-01-01": 63.65,
    "2022-02-01": 55.66,
    "2022-03-01": 33.73,
    "2022-04-01": 26.63,
    "2022-05-01": 29.85,
    "2022-06-01": 40.8,
    "2022-07-01": 43.51,
    "2022-08-01": 44.98,
    "2022-09-01": 42.96,
    "2022-10-01": 41.53,
    "2022-11-01": 43.72,
    "2022-12-01": 51.22,
    "2023-01-01": 55.3,
    "2023-02-01": 61.19,
    "2023-03-01": 65.36,
    "2023-04-01": 65.79,
    "2023-05-01": 67.77,
    "2023-06-01": 73.93,
    "2023-07-01": 75.53,
    "2023-08-01": 70.82,
    "2023-09-01": 73.54,
    "2023-10-01": 84.36,
    "2023-11-01": 82.6,
    "2023-12-01": 74.62,
    "2024-01-01": 83.39,
    "2024-02-01": 96.84,
    "2024-03-01": 117.25,
    "2024-04-01": 104.64,
    "2024-05-01": 113.03,
    "2024-06-01": 119.18,
    "2024-07-01": 105.58,
    "2024-08-01": 97.88,
    "2024-09-01": 91.68,
    "2024-10-01": 93.6,
    "2024-11-01": 93.47,
    "2024-12-01": 82.66,
    "2025-01-01": 81.14,
    "2025-02-01": 82.8,
    "2025-03-01": 77.91,
    "2025-04-01": 84.94,
    "2025-05-01": 75.52,
    "2025-06-01": 75.29,
    "2025-07-01": 79.6,
    "2025-08-01": 84.77,
    "2025-09-01": 93.39,
    "2025-10-01": 91.05,
    "2025-11-01": 81.77,
    "2025-12-01": 76.1
  },
  "filters": {
    "categories": [
      3
    ],
    "regions": [
      42
    ]
  }
}

Response

Job accepted. Use job_id to poll status.

job_idstring uuid

Unique job id — use this to poll status and download artifacts.

poll_urlstring

Convenience URL for polling this job's status.

run_idstring

Internal run identifier (opaque; useful for support).

workflowstring

Internal workflow identifier (opaque; useful for support).