Forecast from numerical history

Submit numerical series or authorized metrics to Mach-1, use supported drivers, and retrieve saved forecasts through REST or MCP.

Mach-1 forecasting predicts future values from numerical history or an authorized registered metric. It is available independently of transcription: bring a series you already have, or use a measured series derived from your operational data.

Before you start

In Build → Developers, create a scoped key with Submit forecasts and Read forecasts. Conversation submission and read permissions are separate.

You need a consistent interval, timezone, history start, numerical values, and forecast horizon. Choose auto for bounded method evaluation, or an explicitly supported method. Review forecasting pricing.

Submit a numerical series

Save this synthetic example as forecast.json. It asks for four future daily points from one target series.

{
  "method": "auto",
  "source": {
    "type": "numerical",
    "grain": "day",
    "timezone": "UTC",
    "historyStart": "2026-01-01T00:00:00Z",
    "horizon": 4,
    "series": [
      {
        "id": "daily-contacts",
        "values": [42, 45, 48, 43, 51, 36, 31, 44, 47, 50, 46, 54, 38, 33, 46, 49, 52, 48, 56, 40, 35, 48, 51, 54, 50, 58, 42, 37]
      }
    ]
  }
}

Set MACH1_API_KEY, MACH1_WORKSPACE_ID, and a new MACH1_FORECAST_KEY in your application’s environment. Persist the key with this exact request before sending.

curl --fail-with-body -X POST \
  "https://build.aioncx.com/api/forecasts?workspace_id=$MACH1_WORKSPACE_ID" \
  -H "Authorization: Bearer $MACH1_API_KEY" \
  -H "Idempotency-Key: $MACH1_FORECAST_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @forecast.json

A queued or running response returns run_id, status, and results_url. Keep the run ID and returned price. A 202 response means the work was accepted and is still in progress.

Retrieve the forecast

Set MACH1_RUN_ID to the returned run ID.

curl --fail-with-body --get \
  "https://build.aioncx.com/api/forecasts/$MACH1_RUN_ID" \
  -H "Authorization: Bearer $MACH1_API_KEY" \
  --data-urlencode "workspace_id=$MACH1_WORKSPACE_ID" \
  --data-urlencode "limit=50" \
  --data-urlencode "quantiles=0.05,0.5,0.95"

Poll until the status is completed or failed. Completed responses contain forecast rows and an optional next_cursor. Retain the same run and quantile selection across pages.

Rows include the interval, series/dimensions, predicted_value, available bounds, and method metadata. Available quantiles describe the forecast distribution. predicted_value can differ from P50: read point_statistic, interval_statistic, and quantile_space when interpreting them.

Add drivers

A numerical series can include up to eight numeric or categorical drivers.

• A past_only driver supplies values for the history.
• A known_future driver supplies values for history and the requested future horizon.
• Its mask states which values are known. Optional availableAt timestamps preserve when information became available.
• Use auto or timestral for explicit numerical drivers.

Align driver arrays with the target history and horizon. A backtest must use only the information available at each forecast origin. Supported drivers and uncertainty output are included in the bounded request.

Forecast a registered metric

Use MCP mach1_list_forecast_sources with the granted workspace_id to discover available metrics, dimensions, and grains. Then submit a source.type of metric with the discovered reference and an explicit history window.

Discovery establishes catalog support. The run separately checks source access and the requested observed history.

Use MCP

Discover visible tools, then call mach1_submit_forecast with request set to the same JSON object and a stable idempotency_key. Read the result with mach1_get_forecast. See the agent quickstart and forecasting REST reference.

Limits and recovery

Limit	Current boundary
Target series	4 per numerical request
Historical target buckets	32,768 total across numerical series
Future forecast points	10,000 total across numerical series
Drivers	8 per series
Auto evaluation	Up to 3 folds
REST request body	1 MiB
Complete MCP request	64 KiB
Grains	15 minutes, 30 minutes, hour, day, week

Use null for missing observations and zero for measured zero. Numerical series in one request must have the same history length and unique IDs.

After an uncertain submission, retry the identical request with its original key. A changed request needs a new key. Read retained results without starting another run. For 403, check forecast grants, workspace selection, and current source access. For 503, retain the request and follow the retry guidance.