> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aioncx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.aioncx.com/mach1/forecasting-pricing.md).

## Submit a numerical series

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

```json theme={"system"}
{
  "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.

```bash theme={"system"}
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.

```bash theme={"system"}
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](https://docs.aioncx.com/agents/quickstart.md) and [forecasting REST reference](https://docs.aioncx.com/api-reference/forecasting/overview.md).

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.