openapi: 3.0.3
info:
title: Transmission Ratings and Operating Limits Information Exchange (TROLIE)
x-logo:
altText: TROLIE logo
url: images/TROLIE-horizontal-color.svg
description: |
This specification defines a set of operations for the exchange of power
system ratings and limits between entities that own and operate the electric
power system in North America. In particular, it is designed to support the
exchange of Ambient Adjusted Ratings (AARs), pursuant to FERC Order 881. It
is published as a community standard to facilitate interoperability
in these exchanges.
The specification conceives of the exchange as being between two primary
entities:
* A [Ratings Provider](https://trolie.energy/concepts#ratings-provider) is
an entity that is responsible for providing ratings on some set of power
system resources, e.g., Transmission Facilities, typically a Transmission
Owner or Transmission Operator. The ratings are provided to a
Clearinghouse Provider whose is responsible for determining the operating
limits of the power system resources.
* The [Clearinghouse Provider](https://trolie.energy/concepts#clearinghouse-provider) is
typically a Transmission Provider (FERC) and a Reliability Coordinator (NERC).
Adjacent Clearinghouse Providers exchange ratings in order to establish
operating limit values for the power system resources that are shared
between them.
A Ratings Provider is assumed by this specification to have pre-coordinated
with a Clearinghouse Provider to identify the former's Ratings Obligation,
i.e., the set of power system resources for which they will provide ratings.
Additionally, the Ratings Provider will have similarly pre-coordinated the
definition of their Monitoring Sets, i.e., their power system limits of
interest. The nature and method of pre-coordination is out-of-scope for this
specification.
Note that this API makes a strict distinction between the terms rating and
limit. Colloquially, these terms are often used interchangeably. However,
in the context of this specification, they have distinct meanings. At a
high-level, the specification defines an exchange where ratings go in and
limits come out. A Clearinghouse is a function for determining the operating
limits from the ratings it has on-hand, including those that are proposed by
Ratings Providers and any applicable time-bound static ratings.
This interaction diagram highlights the primary requests and responses that
are defined in this spec. Note that not all of the operations will be
supported by every implementation.
<img src="images/interactions.excalidraw.png" alt="Primary Interactions with Ratings Provider" />
version: 1.1.0
contact:
name: TROLIE Maintainers
email: maintainers@trolie.energy
url: https://trolie.energy
license:
name: Community Specification License 1.0
url: https://spdx.org/licenses/Community-Spec-1.0.html
servers:
- url: https://trolie.example.com
security:
- oauth2-primary-flow: []
tags:
- name: Real-Time
description: |
If permitted by the Clearinghouse Provider, its Ratings Providers can use
these functions to exchange real-time ratings, supplementing or replacing
traditional telemetry protocols like ICCP.
These ratings are based on real-time measurements of ambient conditions
and will be used by Transmission Providers for real-time grid operations
processes, including state estimation and real-time markets. The clearing
of real-time ratings may be more frequent than for forecast ratings, but
the frequency is the prerogative of the Clearinghouse Provider.
These ratings may be either AARs or DLRs.
- name: Forecasting
description: |
The Forecasting API operations define the exchange of forecasted ratings,
including the 240-hour-ahead forecasted AAR data exchange required by FERC
Order 881. The operations support submitting rating proposals, querying
in-use limits, and monitoring the health and validity of submissions
against the Rating Provider's obligations.
- name: Seasonal
description: |
Seasonal ratings are static ratings associated with extended durations,
typically months. These are typically used in both planning and
operations.
Power system resources that are exempt from providing AARs generally
operate at a seasonal rating. Even for resources using dynamic ratings, a
seasonal rating is still necessary. This acts as a recourse when a dynamic
rating is unavailable. For example, a dynamic rating
might be unavailable during communication outages or for forecasts beyond
the ten-day period required by FERC Order 881.
- name: Seasonal Overrides
description: |
A Seasonal Override instructs the system to use a temporary static rating
instead of any concurrent Seasonal Rating for a resource.
A typical use case is a so-called 'de-rate' due to a temporary clearance
issue for a transmission facility that is exempt from providing AARs.
Exempt facilities typically operate at a seasonal rating. However, instead
of updating the seasonal rating schedule, a Ratings Provider can send a
Seasonal Override.
During the override period, the Clearinghouse uses the Seasonal
Override rating instead of any scheduled seasonal ratings.
For resources required to provide AARs, a Ratings Provider would issue a
Temporary AAR Exception to address temporary conditions requiring a static
rating.
- name: Temporary AAR Exceptions
description: |
A [Temporary AAR Exception](https://trolie.energy/concepts#temporary-aar-exception) is
provided by the Ratings Provider when a Ratings Obligation cannot be
fulfilled, due to some temporary operating condition impacting the related
power system resource. This could occur in various scenarios:
* An equipment failure.
* An unforeseen condition on a related part of the power grid.
* Some ambient condition that is not part of the model is heating the
line, like a wildfire.
* Something in the surrounding environment is affecting the amount that a
line is allowed to sag. For example, this may occur for lines over
rivers when very large ships pass under them
A Temporary AAR Exception serves two main purposes: documenting the reason
for the exception and providing a temporary rating value set. It is employed
in three distinct circumstances:
1. Firstly, Order 881 mandates documentation and archival of all use of
alternate ratings in lieu of AARs. Ratings Providers should continue to
provide real-time and forecast ratings for the affected resource, but
these should match the rating provided with the Temporary AAR Exception
while the latter is in effect. This temporary rating, and the reason that
it occurred, must be captured in history regardless of the provided
ratings. The reason and the end date of the effective window may be
updated after the object has been created, up to a configurable threshold.
If the Ratings Providers provides ratings that deviate from the static
Temporary AAR Exception rating, the Clearinghouse Provider must decide
whether to use those or the static rating. The Clearinghouse Provider
advise its Ratings Providers on how it will choose ahead of time. This
specification recommends using the dynamic rating provided, but it does
not mandate it.
2. Secondly, Temporary AAR Exceptions apply when the Clearinghouse
Provider is generating forecast rating proposals on behalf of the Ratings Provider, e.g., when lookup tables are provided ahead of time by the Ratings Provider.
Since there is no external ratings, the Clearinghouse Provider
wouldn't otherwise know that a temporary static rating is needed.
3. Finally, for facilities where dynamic ratings are provided, it is
possible that a communications outage or other issue could prevent the
Clearinghouse Provider from receiving the dynamic ratings. In this case,
the Clearinghouse Provider would use a Temporary AAR Exception rating.
- name: Monitoring Sets
description: |
[Monitoring Sets](https://trolie.energy/concepts#monitoring-sets) are
named sets of power system resources that may be used to filter ratings
and limits returned by queries against these APIs. How Monitoring Sets are
defined is beyond the scope of the TROLIE specification, and it is assumed
that the sender and receiver have predefined the appropriate Monitoring
Sets.
- name: limit-type
description: <SchemaDefinition schemaRef="#/components/schemas/limit" />
x-displayName: Limit Type
paths:
/limits/forecast-snapshot:
get:
operationId: getLimitsForecastSnapshot
summary: Limits Forecast Snapshot
tags:
- Forecasting
parameters:
- $ref: '#/components/parameters/offset-period-start'
- $ref: '#/components/parameters/period-end'
- $ref: '#/components/parameters/query-filter'
- $ref: '#/components/parameters/resource-id-filter'
- $ref: '#/components/parameters/static-only'
- $ref: '#/components/parameters/temporal-resolution'
description: |
Returns the latest Limits Forecast the clearinghouse has produced.
This content of the response varies significantly based on the media type requested.
* `application/vnd.trolie.forecast-limits-snapshot.v1+json` simply includes the limits.
* For use cases that require understanding *how* the limits were determined,
the media type `application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json`
is available; it contains the ratings proposals and other factors used to
generate the limits.
Both of these media types support the `include-psr-header` parameter. This
is a boolean parameter that defaults to `true`. When set to `false`, the
`power-system-resource` header is omitted. This can result in smaller
payloads when the client already knows the resource ids in use by the
Clearinghouse Provider.
```http
GET /limits/forecast-snapshot HTTP/1.1
Accept: application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json; include-psr-header=false
```
### Slim Format
The `application/vnd.trolie.forecast-limits-snapshot-slim.v1+json` media type
may be used to request a more concise representation of the data. The
media type parameter `limit-type` is required to specify the type of limit
being requested, for example:
```http
GET /limits/forecast-snapshot HTTP/1.1
Accept: application/vnd.trolie.forecast-limits-snapshot-slim.v1+json; limit-type=apparent-power
```
Additionally, the `inputs-used` parameter may be set to `true` to include
the inputs used to generate the forecast.
```http
GET /limits/forecast-snapshot HTTP/1.1
Accept: application/vnd.trolie.forecast-limits-snapshot-slim.v1+json; limit-type=apparent-power; inputs-used=true
```
Note this format is much more concise but requires significant care in
processing. See [Using Slim Media
Types](../example-narratives/using-slim-media-types) for more details.
Clients SHOULD perform Conditional `GET` using the `If-None-Match` header
and the `ETag` of a previous `GET` response to poll this endpoint. Rate
limiting is done on a per Ratings Provider basis, so requests from
independent clients used by the same provider count against the same
quota.
responses:
'200':
description: The requested operating forecast snapshot is returned.
content:
application/vnd.trolie.forecast-limits-snapshot.v1+json:
schema:
$ref: '#/components/schemas/forecast-limits-snapshot'
example:
snapshot-header:
begins: '2023-07-12T16:00:00-07:00'
source:
provider: X-AMPL
last-updated: '2023-07-12T16:00:00-07:00'
origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
default-emergency-durations:
- name: LTE
duration-minutes: 240
- name: STE
duration-minutes: 30
- name: DAL
duration-minutes: 15
power-system-resources:
- resource-id: 8badf00d
alternate-identifiers:
- name: segmentX
authority: TO-NERC-ID
- name: LINE1 SEG-X
authority: RC-NERC-ID
mrid: 8badf00d
limits:
- resource-id: 8badf00d
periods:
- period-start: '2023-07-12T16:00:00-07:00'
period-end: '2023-07-12T17:00:00-07:00'
continuous-operating-limit:
mw: 160
pf: 1
emergency-operating-limits:
- duration-name: LTE
limit:
mw: 170
pf: 1
- duration-name: STE
limit:
mw: 180
pf: 1
- duration-name: DAL
limit:
mw: 190
pf: 1
application/vnd.trolie.forecast-limits-snapshot.v1+json; include-psr-header=false:
schema:
$ref: '#/components/schemas/forecast-limits-snapshot-elide-psr'
example:
snapshot-header:
begins: '2023-07-12T16:00:00-07:00'
source:
provider: X-AMPL
last-updated: '2023-07-12T16:00:00-07:00'
origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
default-emergency-durations:
- name: LTE
duration-minutes: 240
- name: STE
duration-minutes: 30
- name: DAL
duration-minutes: 15
limits:
- resource-id: 8badf00d
periods:
- period-start: '2023-07-12T16:00:00-07:00'
period-end: '2023-07-12T17:00:00-07:00'
continuous-operating-limit:
mw: 160
pf: 1
emergency-operating-limits:
- duration-name: LTE
limit:
mw: 170
pf: 1
- duration-name: STE
limit:
mw: 180
pf: 1
- duration-name: DAL
limit:
mw: 190
pf: 1
application/vnd.trolie.forecast-limits-snapshot-slim.v1+json; limit-type=apparent-power:
schema:
$ref: '#/components/schemas/forecast-limits-snapshot-slim'
example:
snapshot-header:
begins: '2023-07-12T16:00:00-07:00'
ends: '2023-07-12T18:00:00-07:00'
source:
provider: X-AMPL
last-updated: '2023-07-12T16:00:00-07:00'
origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
default-emergency-durations:
- name: LTE
duration-minutes: 240
- name: STE
duration-minutes: 30
- name: DAL
duration-minutes: 15
power-system-resources:
- resource-id: 8badf00d
alternate-identifiers:
- name: segmentX
authority: TO-NERC-ID
- name: LINE1 SEG-X
authority: RC-NERC-ID
mrid: 8badf00d
- resource-id: f34d3d
alternate-identifiers:
- name: segmentY
authority: TO-NERC-ID
- name: LINE2 SEG-Y
authority: RC-NERC-ID
mrid: 8badf00d
limits:
- - - 160
- 1
- 170
- 1
- 180
- 1
- 190
- 1
- - 161
- 1
- 171
- 1
- 181
- 1
- 191
- 1
- - - 140
- 1
- 150
- 1
- 160
- 1
- 170
- 1
- - 141
- 1
- 151
- 1
- 161
- 1
- 171
- 1
application/vnd.trolie.forecast-limits-snapshot-slim.v1+json; limit-type=apparent-power; inputs-used=true:
schema:
$ref: '#/components/schemas/forecast-limits-snapshot-slim-inputs-used'
example:
snapshot-header:
begins: '2023-07-12T16:00:00-07:00'
ends: '2023-07-12T18:00:00-07:00'
source:
provider: X-AMPL
last-updated: '2023-07-12T16:00:00-07:00'
origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
default-emergency-durations:
- name: LTE
duration-minutes: 240
- name: STE
duration-minutes: 30
- name: DAL
duration-minutes: 15
power-system-resources:
- resource-id: 8badf00d
alternate-identifiers:
- name: segmentX
authority: TO-NERC-ID
- name: LINE1 SEG-X
authority: RC-NERC-ID
mrid: 8badf00d
- resource-id: f34d3d
alternate-identifiers:
- name: segmentY
authority: TO-NERC-ID
- name: LINE2 SEG-Y
authority: RC-NERC-ID
mrid: 8badf00d
limits:
- - - 160
- 1
- 170
- 1
- 180
- 1
- 190
- 1
- - 161
- 1
- 171
- 1
- 181
- 1
- 191
- 1
- - - 140
- 1
- 150
- 1
- 160
- 1
- 170
- 1
- - 141
- 1
- 151
- 1
- 161
- 1
- 171
- 1
inputs-used:
- name: dry bulb temperature (Fahrenheit)
unit: degF
values:
- - 50
- 51
- 52
- 53
- - 46.1
- 46.5
- 47.1
- 48
application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json:
schema:
$ref: '#/components/schemas/forecast-limits-detailed-snapshot'
example:
snapshot-header:
begins: '2023-07-12T16:00:00-07:00'
source:
provider: X-AMPL-RC
last-updated: '2024-07-12T16:00:00-07:00'
origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
default-emergency-durations:
- name: LTE
duration-minutes: 240
- name: STE
duration-minutes: 30
- name: DAL
duration-minutes: 15
power-system-resources:
- resource-id: 8badf00d
alternate-identifiers:
- name: segmentX
authority: TO-NERC-ID
- name: LINE1 SEG-X
authority: X-AMPL-RC
mrid: 8badf00d
limits:
- resource-id: 8badf00d
periods:
- period-start: '2023-07-12T16:00:00-07:00'
period-end: '2023-07-12T17:00:00-07:00'
additional-data:
vendor-specific-data: {}
continuous-operating-limit:
mva: 160
emergency-operating-limits:
- duration-name: LTE
limit:
mva: 165
- duration-name: STE
limit:
mva: 170
- duration-name: DAL
limit:
mva: 180
provenance:
- resource-id: 8badf00d
proposals-considered:
- resource-id: 8badf00d-UTILITY-A-SEG-id
source:
last-updated: '2023-07-12T16:00:00-07:00'
provider: UTILITY-A
origin-id: 8badf00d-UTILITY-A-correlation-id
period-start: '2023-07-12T16:00:00-07:00'
period-end: '2023-07-12T17:00:00-07:00'
continuous-operating-limit:
mva: 150
emergency-operating-limits:
- duration-name: LTE
limit:
mva: 160
- duration-name: STE
limit:
mva: 165
- duration-name: DAL
limit:
mva: 170
inputs-used:
- name: wind-speed
unit: mph
value: 5.2
- name: wind-direction
unit: degrees
value: 277.5
- name: temperature
unit: F
value: 72.1
temporary-aar-exceptions:
- id: https://trolie.example.com/temporary-aar-exceptions/1234
source:
origin-id: 2d8c80e8-f533-4be9-85bf-f7f81eb73d67
provider: UTILITY-A
last-updated: '2025-07-12T16:00:00-07:00'
resource:
resource-id: 8badf00d
start-time: '2025-07-12T16:00:00-07:00'
end-time: '2025-08-01T00:00:00-07:00'
continuous-operating-limit:
mva: 160
emergency-operating-limits:
- duration-name: LTE
limit:
mva: 165
- duration-name: STE
limit:
mva: 170
- duration-name: DAL
limit:
mva: 180
overrides:
- continuous-operating-limit:
mva: 160
emergency-operating-limits:
- duration-name: LTE
limit:
mva: 165
reason: TOI 20250701-01
start-time: '2025-07-01T00:00:00-07:00'
application/vnd.trolie.forecast-limits-detailed-snapshot.v1+json; include-psr-header=false:
schema:
$ref: '#/components/schemas/forecast-limits-detailed-snapshot-elide-psr'
example:
snapshot-header:
begins: '2023-07-12T16:00:00-07:00'
source:
provider: X-AMPL-RC
last-updated: '2024-07-12T16:00:00-07:00'
origin-id: //trolie.example.com/snapshots/2024-08-05T11%3a00%3a00-07%3a00
default-emergency-durations:
- name: LTE
duration-minutes: 240
- name: STE
duration-minutes: 30
- name: DAL
duration-minutes: 15
limits:
- resource-id: 8badf00d
periods:
- period-start: '2023-07-12T16:00:00-07:00'
period-end: '2023-07-12T17:00:00-07:00'
additional-data:
vendor-specific-data: {}
continuous-operating-limit:
mva: 160
emergency-operating-limits:
- duration-name: LTE
limit:
mva: 165
- duration-name: STE
limit:
mva: 170
- duration-name: DAL
limit:
mva: 180
provenance:
- resource-id: 8badf00d
proposals-considered:
- resource-id: 8badf00d-UTILITY-A-SEG-id
source:
last-updated: '2023-07-12T16:00:00-07:00'
provider: UTILITY-A
origin-id: 8badf00d-UTILITY-A-correlation-id
period-start: '2023-07-12T16:00:00-07:00'
period-end: '2023-07-12T17:00:00-07:00'
continuous-operating-limit:
mva: 150
emergency-operating-limits:
- duration-name: LTE
limit:
mva: 160
- duration-name: STE
limit:
mva: 165
- duration-name: DAL
limit:
mva: 170
temporary-aar-exceptions:
- id: https://trolie.example.com/temporary-aar-exceptions/1234
source:
origin-id: 2d8c80e8-f533-4be9-85bf-f7f81eb73d67
provider: UTILITY-A
last-updated: '2025-07-12T16:00:00-07:00'
resource:
resource-id: 8badf00d
start-time: '2025-07-12T16:00:00-07:00'
end-time: '2025-08-01T00:00:00-07:00'
continuous-operating-limit:
mva: 160
emergency-operating-limits:
- duration-name: LTE
limit:
mva: 165
- duration-name: STE
limit:
mva: 170
- duration-name: DAL
limit:
mva: 180
overrides:
- continuous-operating-limit:
mva: 160
emergency-operating-limits:
- duration-name: LTE
limit:
mva: 165
reason: TOI 20250701-01
start-time: '2025-07-01T00:00:00-07:00'
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
ETag:
$ref: '#/components/headers/ETag'
'304':
$ref: '#/components/responses/304'
'400':
$ref: '#/components/responses/400-problem'
'401':
$ref: '#/components/responses/401-empty'
'403':
$ref: '#/components/responses/403-empty'
'404':
$ref: '#/components/responses/404-empty'
'406':
$ref: '#/components/responses/406'
'422':
description: Unprocessable Content. The requested `temporal_resolution` is not supported.
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
content:
application/problem+json:
schema:
type: object
allOf:
- properties:
supported-values:
type: array
maxItems: 100
items:
$ref: '#/components/schemas/schema'
- $ref: '#/components/schemas/problem'
required:
- supported-values
example:
type: //trolie.example.com/spec/client-errors/422/unsupported-temporal-resolution
title: Unsupported Temporal Resolution
status: 422
detail: The requested `temporal-resolution` 'PT1M' is not supported. Please choose from the list of supported values.
instance: /forecast?temporal-resolution=PT1M
supported-values:
- PT1H
- P1D
- P1W
- P1M
'429':
$ref: '#/components/responses/429-empty'
'500':
$ref: '#/components/responses/500-empty'
default:
$ref: '#/components/responses/500-empty'
security:
- oauth2-primary-flow:
- read:operating-snapshot
/limits/forecast-snapshot/{period}:
get:
operationId: getHistoricalLimitsForecastSnapshot
summary: Historical Limits Forecast Snapshot
tags:
- Forecasting
parameters:
- $ref: '#/components/parameters/
# --- truncated at 32 KB (330 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spp/refs/heads/main/openapi/trolie-standard-openapi.yml