This article assumes some familiarity with HTTP in general and RESTful APIs in particular (background). It also follows very similar patterns to the concepts for forecast ratings, so the examples on forecast ratings may be helpful for background.

Simplified Example: Transmission Owner Sends Ratings with curl

If a Transmission Owner is their own Ratings Provider, they must regularly send real-time ratings to their Transmission Provider. TROLIE provides the postRealTimeProposal operation for this purpose.

Assume the Transmission Owner creates a file called input.json containing their ratings measurements. An example of the required format for the file is given below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

{
  "proposal-header" : {
    "source": {
      "last-updated": "2025-10-31T15:05:43.044267100-07:00",
      "provider": "UTILITY-A",
      "origin-id": "5aeacb25-9b65-4738-8a00-ac10afa63640"
    },
    "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"}
        ]
      }
    ]
  },
  "ratings": [
    {
      "resource-id": "8badf00d",
      "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": 170
          }
        }
      ]
    }
  ]
}

The format is one of TROLIE’s supported media types named application/vnd.trolie.rating-realtime-proposal.v1+json.

Pushing input.json to TROLIE with curl

Given the above input.json, run the following command to send it to the TROLIE server:

1
2
3
4
5
6

curl -d @input.json \
-X POST \
-H "Content-Type: application/vnd.rating-realtime-proposal.v1+json" \
-H "Accept: application/vnd.trolie.rating-realtime-proposal-status.v1+json"
-o output.json \
"https://trolie.example.com/rating-proposals/real-time"

If this submission is successful, output.json will contain the contents of the response from TROLIE. The format of the response is defined by another TROLIE media type: application/vnd.trolie.rating-realtime-proposal-status.v1+json. An example of this response format is given below:

1
2
3
4
5
6
7
8
9
10
11
12

{
  "source": {
    "provider": "UTILITY-A",
    "last-updated": "2023-07-12T15:05:43.044267100-07:00",
    "origin-id": "5aeacb25-9b65-4738-8a00-ac10afa63640"
  },
  "incomplete-obligation-count": 0,
  "incomplete-obligations": [],
  "invalid-proposal-count": 0,
  "proposal-validation-errors": []
}

Invalid Ratings for Individual Resources Should be Tolerated

The TROLIE spec supports allowing some individual ratings to be invalid without rejecting the entire proposal, much like with forecasts.
The pattern for incomplete and invalid proposals is similar to the one described for forecasts illustrated in Forecast Submittal.

incomplete-obligation-count as a Monitoring Function

The use of the proposal status in realtime will differ somewhat from the usage with forecast ratings. The forecast obligation always applies to a particular window. Real-Time ratings, in contrast, are always simply updated against the current time. The real-time Clearinghouse may run more frequently than once an hour, and rating proposals may be run even more, or less frequently than the Clearinghouse.

In addition to flagging data that is missing, the incomplete-obligation-count also flags data that is considered too “stale” to use. The definition of what is considered stale is ultimately up to the Clearinghouse implementation. If supported by the Clearinghouse, incomplete-obligation-count may also consider obligations for resources that would normally not have their ratings submitted as TROLIE proposals, but rather through other means, such as ICCP.

Therefore, clients should rely more on asynchronous use of getRealTimeProposalStatus as a way to monitor whether the Clearinghouse considers their ongoing data stream healthy.

Jointly-Owned Facilities

In a jointly-owned facility there may be one or more Ratings Providers for a given facility. This is expected to be fairly typical on seams. The pattern is nearly identical to the way this works for forecasts, with the exception that the Clearinghouse may run much more frequently. From a submittal perspective, this is inconsequential: Each Ratings Provider simply submits their own Ratings Proposal for their Ratings Obligation using the appropriate resource-id. As with all resource-id uses, the TROLIE spec is agnostic as to which kind of Power System Resource is nominated by the identifier, but it will typically be a Segment in the case of a Jointly-Owned Facility with multiple Ratings Providers.