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

# Forecasting REST API

> Submit a bounded Mach-1 forecast and retrieve its saved status and results using scoped forecast permissions.

The Mach-1 forecasting API accepts numerical history or a registered metric and returns a saved prediction run. REST and MCP use the same request schema, prediction execution, and retained results.

| Operation | REST | MCP |
| - | - | - |
| Submit a forecast | `POST /api/forecasts?workspace_id=...` | `mach1_submit_forecast` |
| Read status/results | `GET /api/forecasts/{runId}?workspace_id=...` | `mach1_get_forecast` |
| Discover registered metric sources | Use the forecast-source MCP discovery tool | `mach1_list_forecast_sources` |

Create a scoped key in **Build → Developers** with the applicable **Submit forecasts** and **Read forecasts** permissions. Send `Authorization: Bearer <key>`. The forecasting REST selector is the `workspace_id` query parameter; conversation APIs have their own workspace selectors.

## Request

Send the `ForecastRequestSchema` body with a stable `Idempotency-Key`. Its `method` defaults to `auto` and its `source.type` selects `numerical` or `metric`. The [generated OpenAPI reference](https://docs.aioncx.com/api-reference/forecasting/openapi.json) describes the input schema and endpoints.

Numerical input supplies an interval, timezone, history start, horizon, and aligned target series. Metric input supplies the discovered metric and object type, history window, interval, horizon, and optional dimensions, filters, and declared companion inputs.

## Response

Submission returns `run_id`, `status`, the retained `price`, and `results_url`. Draft, queued, and running submissions return HTTP 202; other returned states use HTTP 200.

Read responses contain `run_id`, `status`, `method`, `method_version`, `rows`, and `next_cursor`. Before completion, rows are empty because the run is still processing. A failed run returns `error: "forecast_failed"`.

Completed rows include series/dimensions, interval bounds, operational point, available interval bounds, and selected quantiles with their interpretation metadata. The default read page is 50 rows with P05, P50, and P95. Available uncertainty depends on the method and result.

## Errors

| HTTP status | Meaning |
| - | - |
| 400 | Invalid JSON, unsupported forecast input, invalid cursor, or invalid quantile selection |
| 401 | Invalid or expired credential |
| 403 | Missing forecast grant, workspace access, or current source authority |
| 404 | Forecast unavailable to this reader |
| 409 | Idempotency key reused with different request content |
| 413 | Request exceeds the transport boundary |
| 415 | Submission content type must be application/json |
| 503 | Forecast service unavailable; an uncertain submission can be retried with the same payload and key |

REST errors use `{"error":"code"}`; unavailable service responses also include `retryable: true`. MCP has its own structured tool-error envelope. See the [task guide](https://docs.aioncx.com/mach1/forecasting.md) for a complete synthetic request and [pricing](https://docs.aioncx.com/mach1/forecasting-pricing.md) for current forecasting charges.


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