Sign in

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 60 monthly observations (5 years) 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

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 strictly less than soft_horizon. Maximum 12.

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.

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 strictly less than 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 60 monthly observations (5 years of history) aligned to the first of each month.

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).

Changes