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

# Priority model

> How limit profiles, priorities, and effective limits work

Location and charger limits are controlled through **priority-windowed
profiles**, shared across the location, charger, and cluster endpoints.

## Priority levels

* Priorities range from **0 (lowest) to 10 (highest)**, following the same
  convention as OCPP charging-profile stack levels.
* Each target (a location, or a charger connector) can have **up to 11
  profiles** — one per priority level — each with its own
  `[startTime, endTime)` window.
* Submitting a new profile at a priority that already exists for that target
  **replaces** the existing one.

## Effective limit

At any given moment, the **effective limit** is the `limitKw` of the
**highest-priority profile whose window is currently active**
(`startTime <= now < endTime`).

If no profile is currently active:

* **Locations** fall back to `permanentLimitKw` (set via
  `PUT /locations/{locationId}/limit`).
* **Chargers** have no fallback — outside an active window, the connector is
  not priority-locked and is managed by normal load management.

## Automatic apply/revert

Profiles are applied and reverted automatically at their `startTime`/`endTime`
— **no further API calls are required** once a profile is created.

Profile records are **never deleted** when they expire, so the full history of
profiles remains queryable via `GET /locations/{locationId}/limits` and
`GET /organizations/limits`.

## Status values

Every profile reports a computed `status`:

| Status      | Meaning                            |
| ----------- | ---------------------------------- |
| `SCHEDULED` | `now < startTime` — not yet active |
| `ACTIVE`    | `startTime <= now < endTime`       |
| `EXPIRED`   | `now >= endTime`                   |

## Charger-level locks

`POST /chargers/{controllerUuid}/connectors/{connectorId}/schedules` creates a
profile for a single connector. While **ACTIVE**, the connector is
priority-locked: it is excluded from normal load management and runs
unthrottled up to `limitKw` — it is only throttled (never below its 6A
minimum) as a last resort if the location as a whole is over its grid limit.

## Clusters

A [cluster](/api-reference/energy-management/apply-cluster-schedule)
groups multiple locations under a single optional kW cap. When the cluster's
combined draw would exceed `limitKw`, each member location's effective limit
is scaled down proportionally:

```
scale = min(1, clusterLimitKw / sum(memberLocationLimits))
locationEffectiveLimit = locationSetLimitKw * scale
```

`POST /clusters/{clusterId}/schedules` applies one `LimitProfileRequest` to
every location in the cluster at once.