Run a prediction

A run queues one prediction using an active forecaster's current executable version. It records the subject and evaluation date before the workflow retrieves evidence and calls the model. The result is asynchronous.

What you need

You need a Semogram account with project access, an active equipment forecaster, a published evidence release that returns the intended subject, matching input/output schemas and a configured forecasting/model/workflow runtime. For an equipmentId-to-subject_ref query, use P-101; another query may require a different subject identifier. Inspect its contract rather than guessing.

Set the two window values

Horizon is the label supplied to the prompt, such as 7d. horizonEndsAt is the actual future timestamp used to determine evaluation eligibility. Keep them consistent. UI duration horizons can derive an evaluation date; direct MCP calls must provide horizonEndsAt explicitly. Month/year labels use calendar arithmetic in the UI, unlike fixed hour/day/week durations.

Run Equipment failure risk for subject P-101 over the next seven days. Set the evaluation date to seven days from this run, not the illustrative fixed date in the docs. Show the selected forecaster version and pinned evidence release before running.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "forecast_run",
    "arguments": {
      "forecasterSlug": "equipment-failure-risk",
      "subjectRef": "P-101",
      "horizon": "7d",
      "horizonEndsAt": "2027-01-08T08:00:00Z",
      "params": {},
      "idempotencyKey": "<UNIQUE_RUN_KEY>"
    }
  }
}

Replace the illustrated end date with seven days after your actual invocation. A past date is rejected. Resolved params merge forecaster defaults with run params; explicit run keys win. Default horizon applies if the run omits it. Input validation checks subject_ref, the resolved horizon and params before execution.

Read the record

Use the returned predictionId with prediction_get. Status progresses through Queued and Running to Completed, Failed or Cancelled. Completed means a valid output was saved. Outcome status is independent and may still be Pending.

If invoking through an external assistant, ask it to report the selected version/release, actual UTC evaluation date and saved prediction ID. The in-app forecaster creation assistant builds definitions; use the Run prediction page for invocation.

Retry and cancellation

Use a unique idempotencyKey for each intended new forecast_run operation. If an operation's result is uncertain, retry that same payload/key to recover it rather than creating duplicate forecasts. A deliberate rerun is a new prediction record and should use a new key.

prediction_cancel takes id (the prediction UUID), confirm true and an idempotencyKey. The UI exposes Cancel while applicable. Read the resulting state. Cancellation cannot erase an already completed HTTP/plugin side effect; inspect external operation history if execution was interrupted.

Operate the invocation

See Failures and recovery for dispatch uncertainty, external effects and deliberate reruns, and Monitoring for execution/evidence checks.