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 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 for a complete synthetic request and pricing for current forecasting charges.