# RVOL data endpoints

RVOL provides read-only realized-volatility forecasts, realized actuals, asset coverage, model versions, and feature-family summaries through the PolyBridge API.

Use RVOL to see how volatile an asset is expected to be over a horizon, then compare that forecast with realized volatility after the window closes.

## Access

| Item | Value |
| --- | --- |
| Base URL | `https://api.polybridge.ai` |
| Endpoint family | `GET /v1/rvol/*` |
| Authentication | Bearer API key |
| Required scope | `rvol:read` |
| Anonymous access | Not supported |

Use the normal PolyBridge API-key flow. Approved accounts receive `rvol:read` on eligible keys. Non-approved keys can use Search and Forecast, but RVOL requests return `403`.

## Endpoints

| Endpoint | Returns |
| --- | --- |
| `GET /v1/rvol/models` | List public model identifiers, versions, and aliases. |
| `GET /v1/rvol/assets` | List covered assets and default horizons. |
| `GET /v1/rvol/latest` | Return latest forecasts by asset, horizon, model, or version. |
| `GET /v1/rvol/history` | Return historical forecasts over a date window. |
| `GET /v1/rvol/actuals` | Return realized-volatility actuals. |
| `GET /v1/rvol/features/latest` | Return latest feature-family summaries. |

## Examples

Assets:

```bash
curl -sS "https://api.polybridge.ai/v1/rvol/assets" \
  -H "Authorization: Bearer $POLYBRIDGE_API_KEY"
```

Latest forecasts:

```bash
curl -sS "https://api.polybridge.ai/v1/rvol/latest?asset=spx_index&horizon=21d" \
  -H "Authorization: Bearer $POLYBRIDGE_API_KEY"
```

Actuals:

```bash
curl -sS "https://api.polybridge.ai/v1/rvol/actuals?asset=spx_index&horizon=21d" \
  -H "Authorization: Bearer $POLYBRIDGE_API_KEY"
```

## Responses

RVOL returns public rows. Use OpenAPI for the full schema.

| Field | Meaning |
| --- | --- |
| `model_id` | Public model identifier, such as `rvol-baseline` or `rvol-advanced`. |
| `model_version` | Model version. |
| `asset` | Asset key, such as `spx_index`. |
| `horizon` | Forecast or actuals horizon, such as `21d`. |
| `as_of` | Timestamp for the row. |
| `target_start_at` | Start of the target window. |
| `target_end_at` | End of the target window. |
| `prediction` | Forecast value object. |
| `prediction_value` | Primary forecast variance scalar. |
| `forecast_variance` | Predicted variance over the requested horizon. |
| `forecast_volatility` | Square-root volatility value over the requested horizon. |
| `actual` | Realized value object. |
| `actual_value` | Primary realized variance scalar. |
| `realized_variance` | Observed variance over the completed target window. |
| `realized_volatility` | Square-root realized volatility over the completed target window. |
| `feature_families` | Curated public feature-family categories. |

Forecast example:

```json
[
  {
    "model_id": "rvol-baseline",
    "model_version": "2026-07-01",
    "asset": "spx_index",
    "horizon": "21d",
    "as_of": "2026-07-07T00:00:00Z",
    "target_start_at": "2026-07-08T00:00:00Z",
    "target_end_at": "2026-08-06T00:00:00Z",
    "prediction": {
      "forecast_variance": 0.018,
      "forecast_volatility": 0.134,
      "unit": "log_return_variance_over_horizon"
    },
    "prediction_value": 0.018
  }
]
```

Actuals example:

```json
[
  {
    "asset": "spx_index",
    "horizon": "21d",
    "as_of": "2026-07-07T00:00:00Z",
    "target_start_at": "2026-06-08T00:00:00Z",
    "target_end_at": "2026-07-07T00:00:00Z",
    "actual": {
      "realized_variance": 0.016,
      "realized_volatility": 0.126,
      "unit": "log_return_variance_over_horizon"
    },
    "actual_value": 0.016
  }
]
```

Values are illustrative.

## Errors

| Status | Meaning |
| --- | --- |
| `401` | Missing or invalid bearer key. |
| `403` | Key does not include `rvol:read`. |
| `422` | Invalid query parameters. |
| `429` | App-level abuse-prevention limit reached. |

## Rate limits

External approved RVOL access is protected by app-level abuse-prevention limits, separate from Search and Forecast quotas. Contact PolyBridge for higher limits.

## Related

- OpenAPI: `/api/openapi`
- Search endpoint: `/api/search`
- Forecast endpoint: `/api/forecast`
- Authentication: `/api/authentication`
- Rate limits: `/api/rate-limits`