> ## Documentation Index
> Fetch the complete documentation index at: https://docs.causeloop.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Predictions
> Read and act on Causeloop's AI predictions — understand probability scores, impact levels, the forecast chart, probability matrix, and model accuracy metrics.
A **prediction** is a projection of a pattern's fitted hazard model — not an LLM guess. Predictions let you act before an incident happens rather than responding after the fact.
Predictions are generated automatically from every engine run, from patterns whose hazard has been fitted. Each prediction carries a recurrence probability (`p_recurrence`), a time-to-repeat estimate, an impact level, and a time window. Probabilities are read-only projections of the hazard model — they cannot be edited by a human or an LLM; you can only acknowledge or mute a prediction (see [Dismissing a prediction](#dismissing-a-prediction)).
Not every pattern has a prediction. A hazard needs enough events (and timestamps) to fit — patterns below that threshold return `404 NOT_FITTED` with a `reason` (`insufficient_events` or `no_timestamps`) instead of a fabricated curve. The UI renders that reason rather than a fake forecast.
## The Predictions screen
Navigate to **Predictions** in the left sidebar. The top-bar action area contains a **window selector** (7 d / 30 d / 90 d) that controls the data range shown across all panels.
### Summary tiles
Four KPI tiles appear at the top of the page:
| Tile | Description |
| ------------------------- | -------------------------------------------------------------- |
| **Total predictions** | Count of predictions in the selected window |
| **High-probability** | Predictions with probability ≥ 80 % |
| **Above alert threshold** | Predictions above the workspace alert threshold (default 70 %) |
| **Avg probability** | Mean probability across all predictions in the window |
These figures come from `GET /v1/predictions/summary`.
### Risk signals table
Below the tiles, a table lists the top predictions by probability. Each row shows:
* **Pattern name** — links to the [pattern detail page](/product-guide/patterns)
* **Probability** — score from 0.00 to 1.00, displayed as a percentage
* **Impact** — `critical`, `high`, `medium`, or `low`
* **Window** — the prediction time window in days (e.g. `5D WINDOW`)
* **Status pill** — whether the prediction is active or dismissed
Click any row to navigate to the corresponding pattern or to provide feedback on the prediction.
### Composite risk forecast chart
The forecast chart is an interactive time-series showing the workspace-wide composite risk score over the selected window. It combines:
* **Observed series** (solid line) — historical composite risk from confirmed incidents
* **Projected series** (dashed line) — AI extrapolation beyond today
* **Alert threshold line** — horizontal dashed line at your workspace's alert probability (default 70 %)
* **Breach marker** — a labeled point where the projection crosses the alert threshold
Click or arrow-key through any point on the chart to see an exact value tooltip. The projected section of the line is labeled with "PROJECTED" in the tooltip.
The forecast data comes from `GET /v1/predictions/forecast`. You can scope the chart to a single pattern by passing `pattern_id`.
### Probability matrix
The probability matrix is a 5 × 5 heat grid that maps **likelihood** (rows, bottom-to-top: Rare → Almost Certain) against **impact** (columns, left-to-right: Negligible → Severe). Each active prediction is plotted as a signal dot in its corresponding cell.
Cell colors range from green (low risk) through amber and red to dark red (critical). The matrix gives you a portfolio view of where your risk is concentrated.
### Model accuracy panel
The model accuracy panel shows how well the prediction model is calibrated, computed strictly from backtests — never fabricated:
Rolling-origin backtest results over the event log. Higher is better. Displayed as a filled arc gauge.
Mean squared error of the model's probability estimates, from the backtest ledger. Lower is better (0 = perfect). Displayed as a green arc (inverted scale).
The average number of days of advance warning the model provided in backtested folds. Displayed as a number and a mini progress bar.
The accuracy data comes from `GET /v1/predictions/accuracy`, which is computed from backtests only. If no backtest has run yet, the endpoint returns `{"status": "no_backtest_yet"}` and the panel shows an honest empty state instead of placeholder numbers. Run a backtest with `POST /v1/predictions/backtests` (202, async) and poll `GET /v1/predictions/backtests/{job_id}` for per-fold and aggregate results (Brier, calibration curve points, interval coverage, lead time). The eyebrow label (e.g. `EVAL 06·06`) shows the date of the most recent backtest, when one exists.
### Alert rules panel
The alert rules panel displays the active alert rules for this workspace. Each rule shows its name, threshold, time window, and delivery channels. Use the toggle switch to enable or disable a rule.
Alert rules are managed in detail on the [Notifications & Alerts](/product-guide/notifications-alerts) page. The panel here is a convenience view of the same data.
## Filtering predictions
Use the query parameters on `GET /v1/predictions` to filter the list:
| Parameter | Description |
| ----------------- | --------------------------------------------------------- |
| `min_probability` | Minimum probability (0.0–1.0) |
| `max_probability` | Maximum probability (0.0–1.0) |
| `impact` | `critical`, `high`, `medium`, or `low` |
| `pattern_id` | Scope to a single pattern |
| `window_days` | Prediction window in days |
| `sort` | `-probability` (default), `-generated_at`, `-window_days` |
## Providing feedback
After an event window closes, you can tell Causeloop whether a prediction was correct. This feedback is used to improve the model over time.
Locate the prediction in the list or navigate to it via its pattern.
Call `POST /v1/predictions/{id}/feedback` with `outcome: "correct"` or `"incorrect"` and an optional `notes` field.
## Dismissing a prediction
If a prediction is no longer relevant (for example, the trigger event was cancelled), you can dismiss it via `PATCH /v1/predictions/{id}` with `status: "dismissed"`. This is the only kind of edit a prediction accepts — the `PATCH` payload shrinks to `{status, notes}`; you can acknowledge or mute a prediction, but you cannot edit its probability. Dismissed predictions are hidden from the default list view but remain in the audit trail.
## API reference
| Endpoint | Description |
| ---------------------------------------- | ------------------------------------------------------------------------------------------- |
| `GET /v1/predictions` | List predictions with filters and pagination |
| `GET /v1/predictions/{id}` | Get a single prediction |
| `PATCH /v1/predictions/{id}` | Update `{status, notes}` only — probabilities are read-only |
| `POST /v1/predictions/{id}/feedback` | Record outcome feedback (feeds the backtest ledger) |
| `GET /v1/predictions/summary` | KPI counters for the summary tiles, aggregated over fitted hazards |
| `GET /v1/predictions/forecast` | `observed[]` (real arrival counts from the event log) vs. `projected[]` (Λ(t) buckets) |
| `GET /v1/predictions/accuracy` | Backtest-derived precision / recall / Brier / lead time, or `{"status": "no_backtest_yet"}` |
| `POST /v1/predictions/backtests` | Trigger a rolling-origin backtest (202, async) |
| `GET /v1/predictions/backtests/{job_id}` | Poll backtest results |
| `GET /v1/patterns/{id}/hazard` | Canonical hazard resource a prediction is projected from |
| `GET /v1/dashboard/forecast` | Forecast data for the Dashboard |
## Related pages
Understand the patterns driving each prediction.
Create alert rules that fire when predictions cross a threshold.
Act on the AI's recommended fix before the prediction materialises.
See the top predictions and model accuracy at a glance.