Get Recurring Pricing Schedule Entries
---------------------------------------

Retrieve a paginated list of recurring pricing schedule entries for \
a cost rate, optionally filtered to a weekday + time-of-day window. \
The cost rate must have ``dynamic_pricing`` set to ``1`` \
(recurring per weekday — see :ref:`dynamic-pricing-modes`).

Each entry carries its full pricing payload — ``validity`` (the list \
of weekday/time-range pairs that make up the schedule), ``intervals`` \
(energy + time + session fee, scoped to the entry only) and \
``marketing_texts`` (locale-keyed, resolved with field-level fallback \
from the cost rate).

The window is interpreted in minute-of-week space and **wraps Sunday \
night to Monday morning** when ``to_*`` evaluates to an earlier point \
than ``from_*`` (e.g. ``from_weekday=5&from_time=22:00`` together with \
``to_weekday=1&to_time=06:00`` matches entries running Fri 22:00 \
through Mon 06:00).

**Request**

- Method: ``GET``
- Path: ``/api/dynamic_pricing/recurring_schedule/{cost_rate_uuid}``

**Path parameters**

.. list-table::
   :widths: 20 15 65
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - cost_rate_uuid
     - string
     - UUID of the cost rate. Must have ``dynamic_pricing`` set to \
       ``1`` (recurring per weekday).

**Query parameters**

.. list-table::
   :widths: 18 12 70
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - from_weekday
     - integer|null
     - Optional. ``0`` = Sunday, ``6`` = Saturday. Must be paired with \
       ``from_time`` (half-present returns ``400``).
   * - from_time
     - string|null
     - Optional. ``HH:MM`` 24-hour format. Must be paired with \
       ``from_weekday``.
   * - to_weekday
     - integer|null
     - Optional. Same range as ``from_weekday``. Must be paired with \
       ``to_time``. If omitted while ``from_*`` is given, defaults to \
       end-of-day of ``from`` (``from_weekday`` with ``23:59``); the \
       window is then closed at the end of the ``from`` weekday and \
       does **not** wrap to the following week.
   * - to_time
     - string|null
     - Optional. ``HH:MM`` 24-hour format. Must be paired with \
       ``to_weekday``.
   * - offset
     - integer
     - Page offset, ``>= 0``. Defaults to ``0``. Non-numeric values \
       are treated as ``0``.
   * - limit
     - integer
     - Page size. Defaults to ``100``, clamped to ``[1, 500]``.
   * - locales
     - string|string[]
     - Optional. Restricts the ``marketing_texts`` map on each entry \
       to the requested locale codes. Accepts \
       ``?locales[]=en_US&locales[]=de_DE`` or single \
       ``?locales=en_US``. Omit the parameter entirely to return every \
       locale the cost rate has. Non-string entries are dropped \
       silently.

Omitting all four ``from_*`` / ``to_*`` parameters returns every \
recurring schedule entry on the cost rate.

**Example request**

.. code-block:: bash

    curl --location --request GET \
      'https://example.beenergised.cloud/api/dynamic_pricing/recurring_schedule/<COST_RATE_UUID>?from_weekday=1&from_time=18:00&to_weekday=1&to_time=22:00&offset=0&limit=100' \
      --header 'x-api-token: <your_token>'

**Response (200)**

.. code-block:: json

    {
      "data": [
        {
          "uuid": "<SCHEDULE_UUID>",
          "name": "Weekday Evening Peak",
          "validity": {
            "type": "recurring",
            "weekdays": [
              {
                "uuid": "<SLOT_UUID>",
                "weekday": 1,
                "weekday_name": "MON",
                "start_time": "18:00",
                "end_time": "22:00"
              },
              {
                "uuid": "<SLOT_UUID>",
                "weekday": 2,
                "weekday_name": "TUE",
                "start_time": "18:00",
                "end_time": "22:00"
              }
            ]
          },
          "intervals": {
            "energy": [
              {"uuid": "<INTERVAL_UUID>", "unit": 1000, "price": 0.55}
            ],
            "time": [],
            "session_fee": null
          },
          "marketing_texts": {
            "en_US": {
              "short_description": "Peak weekday evenings",
              "description": "Higher rate Mon-Tue 18:00-22:00",
              "legal": ""
            }
          }
        }
      ],
      "pagination": {
        "offset": 0,
        "limit": 100,
        "next_offset": null,
        "total": 1
      }
    }

.. note::

   ``validity.weekdays`` is a list — a single recurring schedule entry \
   can carry **different time windows on different weekdays**, so the \
   per-weekday shape is a list of objects rather than a single shared \
   ``start_time`` / ``end_time``. ``weekday_name`` is the 3-letter \
   uppercase label (``SUN`` … ``SAT``).

.. note::

   ``intervals.energy`` and ``intervals.time`` are **scoped to the \
   schedule entry only** — the base cost-rate intervals are not folded \
   in. An entry with no entry-scoped intervals of a given kind returns \
   an empty list for that kind.

**Error responses**

- ``404``: Cost rate not found.

.. code-block:: json

    {
      "status": "error",
      "message": "Cost rate not found"
    }

- ``400``: Validation error — cost rate does not have \
  dynamic_pricing = 1, one of ``from_weekday`` / ``from_time`` (or \
  ``to_weekday`` / ``to_time``) is given without its pair, weekday is \
  outside ``0-6``, or time is not in ``HH:MM`` 24-hour format.

.. code-block:: json

    {
      "status": "error",
      "message": "<validation message>"
    }

- ``500``: Generic server error.

.. code-block:: json

    {
      "status": "error",
      "message": "Internal Server Error"
    }