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

# Predict

> Simulate scenario outcomes from uncertain inputs or forecast a time series, with uncertainty ranges and consistency checks.

Predict runs `model: "simulation"` (named distributions and arithmetic outputs) or `model: "forecast"` (a time series projected ahead). Results arrive through `GET /v1/requests/:id`.

The first request returns 402 with a quote by input size (runs times variables and outputs, or series length times horizon) and time cap. Retry identical inputs with payment, `X-Quote-ID` and an `Idempotency-Key`; the 202 response carries the `request_id`. Invalid inputs are refused before payment; failed runs are refunded; a timeout returns partial work and stays charged.

## Simulation

```json theme={null}
{
  "model": "simulation",
  "time_limit_s": 20,
  "simulation": {
    "runs": 10000,
    "seed": 42,
    "percentiles": [5, 50, 95],
    "variables": [{ "id": "effort", "distribution": { "kind": "triangular", "min": 10, "mode": 20, "max": 40 } }],
    "outputs": [{ "id": "duration", "expression": "effort / 2" }]
  }
}
```

Distributions, with their fields beside `kind`: `fixed(value)`, `uniform(min,max)`, `normal(mean,sd)`, `lognormal(log_mean,log_sd)`, `triangular(min,mode,max)`, `bernoulli(p)`, `discrete(values,weights?)`. Weights are nonnegative, match values in length, and are not all zero.

Expressions use numbers, variable or earlier output ids, `+ - * / ^`, unary minus, parentheses, comparisons, `min`, `max`, `abs`, `sqrt`, `exp`, `log`, `floor`, `ceil`, `clamp(x,lo,hi)` and lazy `if(cond,a,b)`. Nothing else is evaluated.

Limits: 100–100,000 runs (default 10,000), 50 variables, 10 outputs, 1,000-character expressions, 100 discrete values, 20 percentiles. The time cap is 1–120 seconds, default 20.

Each output gets `mean` and `median`, plus `sd`, `mean_standard_error`, `min`, `max` and percentiles. A run with a non-finite output is discarded. The same scenario, seed and version reproduce the answer; an omitted seed is returned in `meta.seed`.

## Forecast

```json theme={null}
{
  "model": "forecast",
  "forecast": {
    "series": [{ "t": "2026-01-05", "y": 1210 }, { "t": "2026-01-12", "y": 1185 }, { "t": "2026-01-19", "y": 1260 }, { "t": "2026-01-26", "y": 1302 },
               { "t": "2026-02-02", "y": 1275 }, { "t": "2026-02-09", "y": 1340 }, { "t": "2026-02-16", "y": 1398 }, { "t": "2026-02-23", "y": 1365 }],
    "horizon": 4,
    "frequency": "weekly",
    "interval_levels": [80, 95],
    "floor": 0
  }
}
```

`t` is an ISO 8601 date or date-time, or an integer index, strictly increasing. `frequency` (`hourly` to `yearly`) is inferred when omitted. Missing steps are interpolated. `seasonal_period` defaults to the frequency's natural cycle and is dropped without two full periods. `floor` clips forecasts and bounds.

Each candidate method is scored on the held-out tail; the best is refitted and projected. The result holds `horizon` point forecasts and intervals per level, named in the input's form; `meta` gives the method and backtest error.

Limits: 8–10,000 points, a horizon of 1–365 steps and at most twice the series length. Short series, long horizons, bad timestamps or values, and series without a regular step are refused before quoting.

## Clients

TypeScript: `await agent.predict(input)`. Python: `client.predict(input)` or `await client.apredict(input)`. Both handle quoting, payment and polling. Use `maxCost` (TypeScript) or `max_cost` (Python) to cap payment.

TypeScript `wait: false` returns a `PredictPendingResult` job handle; `true` or omitted returns the prediction. Runtime booleans return their union.

MCP, LangChain and GAME expose `oneshot_predict` with either model and its matching block. GAME takes the block as a JSON object string.

`invalid_input` includes a `code` and `message`; correct the named field before retrying. Results have `model`, `version`, `status` (`complete` or `timeout`), `prediction`, `uncertainty`, `checks` and `meta`.


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