> ## 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 /market/prices — Historical OMIE Market Prices

> Query historical cleared electricity prices from the Spanish OMIE day-ahead and intraday markets. Filter by session, date range, and hour.

The `GET /market/prices` endpoint lets you retrieve the historical settled prices published by OMIE for any session and date range Nexenergie has on record. Prices cover the day-ahead market as well as intraday sessions 1 through 3, and are indexed by date and hour so you can build precise time-series queries for analysis, backtesting, or model training.

## Endpoint

| Method | Path                    | Auth     |
| ------ | ----------------------- | -------- |
| `GET`  | `/api/v1/market/prices` | Required |

## Query Parameters

<ParamField query="market" type="string" default="day-ahead">
  The market session to query. Must be one of:

  * `day-ahead` — OMIE day-ahead auction
  * `intraday-1` — Intraday session 1
  * `intraday-2` — Intraday session 2
  * `intraday-3` — Intraday session 3
</ParamField>

<ParamField query="date_from" type="string" required>
  Start of the date range to query, inclusive. Format: `YYYY-MM-DD`.
</ParamField>

<ParamField query="date_to" type="string" required>
  End of the date range to query, inclusive. Format: `YYYY-MM-DD`. The range between `date_from` and `date_to` must not exceed **90 days** per request.
</ParamField>

<ParamField query="hour" type="integer">
  Filter results to a specific hour of the day. Accepts integers from `0` (midnight) to `23` (11 PM). When omitted, all 24 hours are returned for each date in the range.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for paginated results. Starts at `1`.
</ParamField>

<ParamField query="page_size" type="integer" default="100">
  Number of records to return per page. Maximum value is `1000`.
</ParamField>

## Request Example

<CodeGroup>
  ```bash curl theme={null}
  curl -G "https://app.nexenergie.ai/api/v1/market/prices" \
    --header "Authorization: Bearer <token>" \
    --data-urlencode "market=day-ahead" \
    --data-urlencode "date_from=2024-05-01" \
    --data-urlencode "date_to=2024-05-31" \
    --data-urlencode "page_size=100"
  ```

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

  url = "https://app.nexenergie.ai/api/v1/market/prices"
  headers = {"Authorization": "Bearer <token>"}
  params = {
      "market": "day-ahead",
      "date_from": "2024-05-01",
      "date_to": "2024-05-31",
      "page_size": 100,
  }

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

  print(f"Total records: {data['total']}")
  for item in data["items"]:
      print(f"{item['date']} H{item['hour']:02d}  →  {item['price']} {item['unit']}")
  ```
</CodeGroup>

## Response

A successful request returns HTTP `200 OK` with a paginated JSON object.

<ResponseField name="total" type="integer">
  Total number of records matching the query across all pages.
</ResponseField>

<ResponseField name="page" type="integer">
  The current page number returned.
</ResponseField>

<ResponseField name="page_size" type="integer">
  The number of records included in this page.
</ResponseField>

<ResponseField name="items" type="array">
  Array of price records matching the query filters.

  <Expandable title="items">
    <ResponseField name="date" type="string">
      Settlement date of the price record. Format: `YYYY-MM-DD`.
    </ResponseField>

    <ResponseField name="hour" type="integer">
      Hour of the day (0–23) to which this price applies.
    </ResponseField>

    <ResponseField name="market" type="string">
      Market session identifier, e.g. `day-ahead`, `intraday-1`.
    </ResponseField>

    <ResponseField name="session" type="integer | null">
      Intraday session number (1–3) for intraday markets. `null` for the day-ahead market.
    </ResponseField>

    <ResponseField name="price" type="number">
      Cleared market price in EUR/MWh as published by OMIE after settlement.
    </ResponseField>

    <ResponseField name="unit" type="string">
      Unit of the price value. Always `"EUR/MWh"`.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={null}
{
  "total": 744,
  "page": 1,
  "page_size": 100,
  "items": [
    {
      "date": "2024-05-01",
      "hour": 0,
      "market": "day-ahead",
      "session": null,
      "price": 48.32,
      "unit": "EUR/MWh"
    },
    {
      "date": "2024-05-01",
      "hour": 1,
      "market": "day-ahead",
      "session": null,
      "price": 44.17,
      "unit": "EUR/MWh"
    },
    {
      "date": "2024-05-01",
      "hour": 2,
      "market": "day-ahead",
      "session": null,
      "price": 41.95,
      "unit": "EUR/MWh"
    }
  ]
}
```

## Error Responses

| HTTP Status        | Reason                                                                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`  | Missing required parameters (`date_from` or `date_to`), invalid format, unsupported `market` value, or date range exceeds the 90-day limit. |
| `401 Unauthorized` | Missing, expired, or invalid Bearer token.                                                                                                  |

<Note>
  Historical prices are published by OMIE only after market settlement has concluded. Prices for the current day may be incomplete or unavailable for recent hours — allow sufficient settlement time before querying today's data.
</Note>

<Tip>
  Use this endpoint to backtest your strategies against historical cleared prices and compare them to Nexenergie's forecasts over the same period. Pairing `market/prices` with `forecasts/day-ahead` on the same date range gives you a direct view of forecast accuracy.
</Tip>