> ## 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/model-performance — Version Comparison

> Compare forecast accuracy across Nexenergie model versions to track improvements over time and validate that newer models perform better for your market.

The `GET /metrics/model-performance` endpoint returns a side-by-side comparison of accuracy metrics for different model versions over a specified date range, helping you understand how the forecasting models have evolved. Each entry in the response corresponds to one model version that was active during the requested window, along with its MAE, RMSE, and MAPE computed against official OMIE settled prices.

## Endpoint

| Property   | Value                                      |
| ---------- | ------------------------------------------ |
| **Method** | `GET`                                      |
| **Path**   | `/api/v1/metrics/model-performance`        |
| **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 comparison window, in `YYYY-MM-DD` format. Must be earlier than `date_to`.
</ParamField>

<ParamField query="date_to" type="string" required>
  End of the comparison window, in `YYYY-MM-DD` format. Both dates are inclusive.
</ParamField>

***

## Request Example

The examples below compare all model versions that served day-ahead forecasts during Q1 2024.

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

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

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

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

  for version in data["versions"]:
      print(
          f"{version['model_version']:10s} "
          f"MAE={version['mae']} EUR/MWh  "
          f"RMSE={version['rmse']} EUR/MWh  "
          f"MAPE={version['mape']}%"
      )
  ```
</CodeGroup>

***

## Response

A successful request returns HTTP `200 OK` with metadata about the query and an array of per-version accuracy objects, ordered by `active_from` ascending (oldest version first).

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

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

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

<ResponseField name="versions" type="array">
  Ordered list of model versions active during the requested date range. Each element contains accuracy metrics computed only from the days that specific version was active.

  <Expandable title="versions items">
    <ResponseField name="model_version" type="string">
      Unique version identifier for this model (e.g. `"v2.3.0"`).
    </ResponseField>

    <ResponseField name="active_from" type="string">
      ISO 8601 timestamp of when this model version became active in production (e.g. `"2024-01-01T00:00:00Z"`).
    </ResponseField>

    <ResponseField name="active_to" type="string">
      ISO 8601 timestamp of when this version was replaced by a newer one. Returns `null` if this version is still currently active.
    </ResponseField>

    <ResponseField name="n_observations" type="integer">
      Number of hourly data points used to compute this version's metrics within the requested date range.
    </ResponseField>

    <ResponseField name="mae" type="number">
      Mean Absolute Error in **EUR/MWh** for this model version over its active window.
    </ResponseField>

    <ResponseField name="rmse" type="number">
      Root Mean Square Error in **EUR/MWh** for this model version over its active window.
    </ResponseField>

    <ResponseField name="mape" type="number">
      Mean Absolute Percentage Error as a percentage for this model version over its active window.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

The response below shows two model versions that were active during Q1 2024, with the newer `v2.4.0` outperforming `v2.3.0` across all three metrics.

```json theme={null}
{
  "market": "day-ahead",
  "date_from": "2024-01-01",
  "date_to": "2024-03-31",
  "versions": [
    {
      "model_version": "v2.3.0",
      "active_from": "2023-10-15T00:00:00Z",
      "active_to": "2024-02-05T00:00:00Z",
      "n_observations": 840,
      "mae": 7.42,
      "rmse": 9.88,
      "mape": 11.53
    },
    {
      "model_version": "v2.4.0",
      "active_from": "2024-02-05T00:00:00Z",
      "active_to": null,
      "n_observations": 1272,
      "mae": 4.97,
      "rmse": 6.43,
      "mape": 8.21
    }
  ]
}
```

***

## Error Responses

| HTTP Status | Code                 | Description                                                                                            |
| ----------- | -------------------- | ------------------------------------------------------------------------------------------------------ |
| `400`       | `invalid_parameters` | A required parameter is missing, `date_from` ≥ `date_to`, or an unsupported market value was supplied. |
| `401`       | `unauthorized`       | The `Authorization` header is missing or the token is invalid or expired.                              |

<Tip>
  Run this endpoint after Nexenergie deploys a model update — you'll notice `model_version` changing in forecast responses — to confirm the new version performs as well or better on your target market before relying on it for high-stakes procurement decisions.
</Tip>

<Note>
  Model versions are managed entirely by Nexenergie and updated automatically. You can monitor version changes and their impact on accuracy through this endpoint, but you cannot select or pin a specific version for new forecasts.
</Note>