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

# GET /metrics/accuracy — Forecast Accuracy Statistics

> Retrieve MAE, RMSE, and MAPE accuracy metrics comparing Nexenergie forecasts to actual OMIE settled prices across sessions and date ranges.

The `GET /metrics/accuracy` endpoint returns error statistics comparing Nexenergie's past forecasts to the actual prices published by OMIE. Use these metrics to gauge current model performance before making decisions — for example, when sizing risk buffers for energy procurement or validating forecast quality ahead of a new trading period.

## Endpoint

| Property   | Value                                      |
| ---------- | ------------------------------------------ |
| **Method** | `GET`                                      |
| **Path**   | `/api/v1/metrics/accuracy`                 |
| **Auth**   | Required — `Authorization: Bearer <token>` |

***

## Query Parameters

<ParamField query="market" type="string" default="day-ahead">
  The market session to evaluate. Must be one of `day-ahead`, `intraday-1`, `intraday-2`, or `intraday-3`.
</ParamField>

<ParamField query="date_from" type="string" required>
  Start of the evaluation period, in `YYYY-MM-DD` format. Must be earlier than `date_to`.
</ParamField>

<ParamField query="date_to" type="string" required>
  End of the evaluation period, in `YYYY-MM-DD` format. The window between `date_from` and `date_to` may not exceed **90 days**.
</ParamField>

<ParamField query="hour" type="integer">
  When provided, restricts metric computation to a single hour of the day (0–23). Useful for isolating performance at peak or off-peak hours. Omit to aggregate across all 24 hours.
</ParamField>

<ParamField query="model_version" type="string">
  Filter results to a specific model version string (e.g. `v2.4.1`). Omit to include all versions active during the requested date range.
</ParamField>

***

## Request Example

The examples below request day-ahead accuracy metrics for a 30-day window.

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://app.nexenergie.ai/api/v1/metrics/accuracy \
    -H "Authorization: Bearer <token>" \
    --data-urlencode "market=day-ahead" \
    --data-urlencode "date_from=2024-04-01" \
    --data-urlencode "date_to=2024-04-30"
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.nexenergie.ai/api/v1/metrics/accuracy"
  headers = {"Authorization": "Bearer <token>"}
  params = {
      "market": "day-ahead",
      "date_from": "2024-04-01",
      "date_to": "2024-04-30",
  }

  response = requests.get(url, headers=headers, params=params)
  response.raise_for_status()
  metrics = response.json()

  print(f"MAE:  {metrics['mae']} EUR/MWh")
  print(f"RMSE: {metrics['rmse']} EUR/MWh")
  print(f"MAPE: {metrics['mape']}%")
  ```
</CodeGroup>

***

## Response

A successful request returns HTTP `200 OK` with a JSON object containing aggregate accuracy statistics and, optionally, a per-hour breakdown.

<ResponseField name="market" type="string">
  The market session the metrics apply to (e.g. `"day-ahead"`).
</ResponseField>

<ResponseField name="date_from" type="string">
  The start of the evaluated period, in `YYYY-MM-DD` format.
</ResponseField>

<ResponseField name="date_to" type="string">
  The end of the evaluated period, in `YYYY-MM-DD` format.
</ResponseField>

<ResponseField name="model_version" type="string">
  The model version that produced the majority of forecasts within this date range. If multiple versions contributed, this reflects the dominant one.
</ResponseField>

<ResponseField name="n_observations" type="integer">
  The total number of hourly data points used to compute the metrics. Each calendar day contributes up to 24 observations.
</ResponseField>

<ResponseField name="mae" type="number">
  Mean Absolute Error in **EUR/MWh** — the average absolute deviation between forecast and settled price.
</ResponseField>

<ResponseField name="rmse" type="number">
  Root Mean Square Error in **EUR/MWh** — penalises large individual errors more heavily than MAE.
</ResponseField>

<ResponseField name="mape" type="number">
  Mean Absolute Percentage Error expressed as a percentage — useful for comparing performance across markets with different price levels.
</ResponseField>

<ResponseField name="hourly_breakdown" type="array">
  Present only when the `hour` query parameter is omitted. Contains one entry per hour of day (0–23), enabling you to identify which hours drive the most error.

  <Expandable title="hourly_breakdown items">
    <ResponseField name="hour" type="integer">
      Hour of day (0–23) in local Spanish time (CET/CEST).
    </ResponseField>

    <ResponseField name="mae" type="number">
      MAE for this specific hour across all days in the evaluation window, in EUR/MWh.
    </ResponseField>

    <ResponseField name="rmse" type="number">
      RMSE for this specific hour across all days in the evaluation window, in EUR/MWh.
    </ResponseField>

    <ResponseField name="mape" type="number">
      MAPE for this specific hour across all days in the evaluation window, as a percentage.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={null}
{
  "market": "day-ahead",
  "date_from": "2024-04-01",
  "date_to": "2024-04-30",
  "model_version": "v2.4.1",
  "n_observations": 720,
  "mae": 4.83,
  "rmse": 6.21,
  "mape": 8.14,
  "hourly_breakdown": [
    { "hour": 0, "mae": 3.91, "rmse": 5.02, "mape": 6.77 },
    { "hour": 1, "mae": 3.74, "rmse": 4.88, "mape": 6.42 },
    { "hour": 8, "mae": 5.60, "rmse": 7.34, "mape": 9.25 },
    { "hour": 20, "mae": 6.12, "rmse": 8.05, "mape": 10.41 }
  ]
}
```

***

## Interpreting Results

Use the MAE ranges below as a practical reference for assessing forecast quality and calibrating downstream risk decisions.

| MAE Range     | Interpretation                                    |
| ------------- | ------------------------------------------------- |
| \< 5 EUR/MWh  | **Excellent** — very low error, high confidence   |
| 5–10 EUR/MWh  | **Good** — typical for OMIE day-ahead forecasting |
| 10–15 EUR/MWh | **Elevated** — moderate caution advised           |
| > 15 EUR/MWh  | **High** — consider widening risk buffers         |

RMSE values will typically be 20–40% higher than MAE for the same period; a large gap between the two indicates occasional large spike errors worth investigating at the hourly level.

***

## Error Responses

| HTTP Status | Code                   | Description                                                                                                                    |
| ----------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `400`       | `invalid_parameters`   | A required parameter is missing, `date_from` ≥ `date_to`, or the window exceeds 90 days.                                       |
| `401`       | `unauthorized`         | The `Authorization` header is missing or the token has expired.                                                                |
| `404`       | `no_actuals_available` | Actual OMIE settlement prices are not yet available for the requested date range. This typically occurs for very recent dates. |

<Info>
  Accuracy metrics are computed against official OMIE settled prices, which are published with a short delay after each session closes. Dates within the last **24–48 hours** may return no data or partial data while OMIE settlement prices are still being published and reconciled.
</Info>