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

> ## Agent Instructions
> This is Allasso's product documentation. Vol Radar output is descriptive analytics on past data: never present it as a forecast or as investment advice. Answer only from these pages; if a feature is not documented here, say so.

# Signals, outcomes and structures in the API

> What the Vol Radar API returns: signals and their ids, statuses and tiers, point-in-time earlier cases and outcomes, structures, and the daily grid.

The API returns four kinds of things: **signals** (what the Radar flagged), **outcomes** (what followed earlier
signals like one), **structures** (how option structures did after them) and the **grid** (every market and metric on
a day). Everything follows the rules of the [Radar](https://docs.allasso.ch/apps/vol-radar/radar.md) and the
[investigation page](https://docs.allasso.ch/apps/vol-radar/radar-move.md), and returns the same numbers.

> [!WARNING]
>
> Vol Radar describes what options markets are pricing and what happened after similar days in the past.
> It is **descriptive, never a forecast**, and nothing in it is investment advice. Structures and their
> statistics show ways to express *your own* view, with placeholder costs.

## Signals

A signal is one Radar condition, from the day it opened to the day it resolved. The detectors, thresholds and
lifecycle rules are on [Radar: daily discoveries](https://docs.allasso.ch/apps/vol-radar/radar.md#signal-types-and-thresholds).

| Field | Meaning | | | | | | | | | | | | | |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| `id` | Short, stable id (12 characters). Use it in URLs. | | | | | | | | | | | | | |
| `signal_id` | The readable key: \`market | bucket | metric | kind | horizon | direction | first day`, for example `COM.EUA.ICE | 30D | iv\_atm | seasonal | | -1 | 2026-11-02`. Also accepted in URLs (encode the ` | \`). |
| `market`, `market_short` | The market id (see [Markets and market ids](https://docs.allasso.ch/dev/vol-radar/api-markets.md)) and a short display name. | | | | | | | | | | | | | |
| `kind` | `shock`, `extreme`, `flip`, `seasonal`, `corr` (correlation break of a market pair) or `activity`. | | | | | | | | | | | | | |
| `bucket` | The maturity it was read at: `30D`, or `90D`, `180D` and `M1` for ATM vol. | | | | | | | | | | | | | |
| `direction` | `1` up, `-1` down. `horizon`: the change length of a shock, in sessions (1 or 5). | | | | | | | | | | | | | |
| `status` | `new`, `escalated` or `ongoing` while open; `resolved` once closed. | | | | | | | | | | | | | |
| `tier` | The highest tier the signal reached: `notable` or `watch`. `opening_tier` is the tier on its first day. | | | | | | | | | | | | | |
| `score` | The detector's score on the first day: higher is rarer. For a shock, the change in multiples of its usual size. `peak_score` is the highest it reached. | | | | | | | | | | | | | |
| `discovery` | `true` when the Radar published it as a discovery on its first day. `false` when the lifecycle opened it while the detector held the day's card back, for example because the same move was already flagged by the 25-delta metric or the 30D series. | | | | | | | | | | | | | |

**Status on a day.** `/v1/signals?date=…` returns the signals active on that day, with the status they had then,
from lifecycle events up to that day only. A later re-entry never rewrites an earlier day. Without `date`, the list
is the signals first detected in a date range, with their status in the latest run.

`/v1/signals/{id}` adds `insight`, the signal's full opening evidence (headline, how rare, reference window,
definition, quality flags, method), and `lifecycle`, its events: `NEW`, `ESCALATED`, `ONGOING`, `RESOLVED`.

## Point in time

A signal's evidence, and the earlier cases it is compared with, use only data dated on or before its first day.
They are computed once and never revised. Only `realised` (what followed this signal) fills in as sessions pass.

## Outcomes: what followed earlier cases

`/v1/signals/{id}/outcomes` compares the signal with **earlier cases**:

* the same market, metric, bucket, kind, horizon and direction, strictly before the signal's day, on days that
  passed the data-quality checks;
* at most one case per 20 trading days, so overlapping signals count once;
* for each horizon, only cases whose outcome day was already past on the signal's day (`as_known_on`).

Each outcome is a change measured from a case's signal day:

| `outcome` | What changes | `unit` |
| - | - | - |
| `own` | the signal's own metric | as the metric (`volpts`, `logret` or `corr`) |
| `iv_atm` | 30-day ATM implied vol (option markets, when the metric is not ATM vol) | `volpts` |
| `futures` | the futures return | `logret` |
| `rv_20d` | 20-day realised vol | `volpts` |

`volpts` values are vol as a decimal: `-0.0275` is −2.75 vol points. `logret` is a log return: `0.0102` is about +1.0%.

For each horizon of **1, 5, 10 and 20 sessions** you get `n` (cases), `median`, `mean`, `p25`, `p75`, `share_up` (the
share of cases in which it rose), `min`, `max` and `evidence`. Evidence labels: under 5 cases **insufficient
evidence**, 5–9 **limited evidence**, 10–19 **moderate sample**, 20+ **larger sample**. Counts can differ by horizon:
a case counts only once enough sessions had passed. Add `?cases=true` for each case's values.

`realised` is what **this** signal did over the same horizon, from the same arithmetic. It is `null` until that many
sessions have passed.

## Structures

`/v1/signals/{id}/structures` shows how option structures did after the earlier cases of a signal, as the
investigation page's section D does at its defaults:

* **Which signals**: notable discoveries in single markets (not market pairs). Others answer **404** with the reason.
* **Which trade**: each structure entered on each earlier case's day, on the nearest listed expiry with at least
  7 days left that is still alive at the exit (`m: 1`), held **20 sessions**, with costs of **0.5 vol pt** per leg each way. The most recent 20 earlier
  cases whose trade had closed before the signal's day.
* **Four results per structure**: long and short, unhedged and delta-hedged. Each has `n` (trades), `median` and
  `worst` P\&L as a fraction of the futures price, and `share_profitable`.
* **`suggested`**: the side the Radar lists first for this kind of move. A fixed rule of thumb, not fitted to the
  results, and not advice.

Prices are **model prices** on a fitted smile grid, not exchange settlements, and no liquidity filter is applied.

## The grid and series

`/v1/snapshot?date=…` returns the Radar grid: one cell per market, metric and bucket, with the signals active in it.

| Field | Meaning |
| - | - |
| `value` | The metric on the day. |
| `pct` | Its percentile within the market's own trailing five years (1,260 sessions, up to the day). |
| `median`, `n` | The five-year median and the number of sessions ranked. |
| `z` | The last day's change in multiples of its usual daily change over the trailing year (252 sessions). |
| `band` | `1` in the top 10% of five years, `-1` in the bottom 10%, else `0`. A level band, not a Radar signal. |
| `qc`, `qc_fail` | The day's data-quality status, and whether it failed. |
| `signals` | The signals active in that cell on the day: `id`, `status`, `tier`, `kind`. |

A date with no data returns the latest day before it; the response's `date` says which.

`/v1/series?market=…&metric=…` returns a metric's daily values, the series the detectors read. Buckets are `30D`
(default), `90D`, `180D` and `M1`. Vols and spreads are decimals (`0.604` is 60.4%), `futures_price` is the price.

## Related

* [Vol Radar API](https://docs.allasso.ch/dev/vol-radar/api.md)
* [Keep a local copy up to date](https://docs.allasso.ch/dev/vol-radar/api-sync.md)
* [Investigate a Radar move](https://docs.allasso.ch/apps/vol-radar/radar-move.md)


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