Event Performance & Interval Data

🚧

Data in Analytics API endpoints and portal tab may differ from settlement reports. Reach out to your Leap account manager with any questions.

Tracking dispatch event performance is an important part of a successful grid services program. Retrieving these event performance metrics as well as utility interval data can be accomplished through the Analytics API endpoints described in this guide.

The meter-level performance endpoint provides energy usage, baseline, and performance measurements in watt-hours for each interval during the event window along with additional metadata on the dispatch event. The meter-level interval data and aggregated interval data endpoints provide raw energy usage in watt-hours for all intervals regardless of whether there was an event or not. The aggregated endpoint combines data from all queried meters to report the cumulative totals for that group of meters.

Common Use Cases

These endpoints can be polled on an ongoing basis to retrieve the latest meter performance and interval data for internal processing. Some common use cases include:

• Analyze event performance data to:
  • Track and analyze performance per meter, customer, market, or region and look for trends
  • Flag poor performing meters for follow-up with customers
  • Track impact of changes being made (e.g. dispatch strategy, technology updates, customer communications, etc.)
  • Compare to your own event and performance metrics (if applicable)
• Retrieve interval load data to see trends and historical usage
• Provide reporting to your customers summarizing these insights

📘

For more information on viewing this data in the Leap partner portal, check out the Analyze Tab Guide in our Knowledge Center (partner portal login required).

Request Parameter Considerations

In order to provide large dataset responses in a timely manner, the following constraints have been put in place for each request and, if hit will result in a 400 error with the corresponding message in the response body:

{
  "date_range_start": "2023-11-10T14:00:00Z",
  "date_range_end": "2023-11-11T14:00:00Z",
  "meter_ids": [
    "e859c532-7852-4d6e-9084-305aa78b496b"
  ]
}

Optional request parameters:

• interval - Interval Data endpoints default to 15-minute intervals whereas the Event Performance endpoint defaults to 1-hour intervals. Both can be changed by using this optional request parameter.
• dispatch_event_types - Event Performance endpoints default to standard, capacity-test, day-ahead, and hour-ahead but this can be changed by using this parameter to choose any combination of event types including more granular real-time events.

📘

Historical Interval Data Availability

Historical interval data is available as long as the utility provides this data to Leap. The amount of historical data Leap receives varies depending on the meter but generally goes back at least 6 months and up to 2 years.

Responses

400 Errors

Request validation errors will result in a 400 error. Be sure to check the response body for additional details on what the error was and how to resolve it. Common errors include:

Response Body

To see descriptions of the fields within each response, click on the green 200 OK box at the bottom of the middle column of each endpoint’s API Reference page.

Event Performance Example

{
  "meters": [
    {
      "meter_id": "591d0f4c-650f-43b5-bcf4-17e680b268f3",
      "summary": {
        "event_energy_wh": 0,
        "baseline_wh": 4398.24,
        "performance_wh": 4398.24,
        "dispatch_quantity_wh": 3893,
        "number_of_events": 1
      },
      "events": [
        {
          "meter_event_id": "ea264b39-7abd-4acc-8607-548c8afda844",
          "start_time_utc": "2023-08-06T01:00:00Z",
          "end_time_utc": "2023-08-06T02:00:00Z",
          "dispatch_quantity_w": 3893,
          "dispatch_event_types": [
            "day-ahead"
          ],
          "program": "CCA",
          "intervals": [
            {
              "start_time_utc": "2023-08-06T01:00:00Z",
              "end_time_utc": "2023-08-06T02:00:00Z",
              "event_energy_wh": 0,
              "baseline_wh": 4398.24,
              "performance_wh": 4398.24
            }
          ]
        }
      ]
    }
  ]
}

Interval Data Example

{
  "meters": [
    {
      "meter_id": "591d0f4c-650f-43b5-bcf4-17e680b268f3",
      "intervals": [
        {
          "start_time_utc": "2023-08-01T14:00:00Z",
          "end_time_utc": "2023-08-01T14:15:00Z",
          "energy_net_wh": 4290,
          "energy_consumed_wh": 4290,
          "energy_generated_wh": 0
        },
        {
          "start_time_utc": "2023-08-01T14:15:00Z",
          "end_time_utc": "2023-08-01T14:30:00Z",
          "energy_net_wh": 4270,
          "energy_consumed_wh": 4270,
          "energy_generated_wh": 0
        },
        {
          "start_time_utc": "2023-08-01T14:30:00Z",
          "end_time_utc": "2023-08-01T14:45:00Z",
          "energy_net_wh": 4350,
          "energy_consumed_wh": 4350,
          "energy_generated_wh": 0
        },
        {
          "start_time_utc": "2023-08-01T14:45:00Z",
          "end_time_utc": "2023-08-01T15:00:00Z",
          "energy_net_wh": 4410,
          "energy_consumed_wh": 4410,
          "energy_generated_wh": 0
        }
      ]
    }
  ]
}

Data Considerations

Below are some considerations to keep in mind when processing and analyzing data provided in the API responses:

Data availability

• CAISO and NYISO markets are currently supported
• Interval data:
  • CAISO utilities - Initial interval data generally provided within 1-2 days but there are occasionally gaps in data or no data at all for some meters and these get filled in over the following days and weeks
  • NYISO utilities - Interval data is updated on a monthly basis a few days after each monthly billing cycle
• Performance data:
  • Event performance metrics are generally available within a few hours of the above interval data being available from utilities but can take up to several days in some cases

Gap-filled intervals

• In some cases, energy data provided by utilities is incomplete, resulting in gaps in a meter’s interval data. Leap is required by regulators to fill all gaps and do so using different algorithms. In some rare cases, none of the algorithms apply and a value of 0 is used.

Watt-hour vs. watt measurements

• Watt-hour data is provided for all energy usage, baseline, and performance metrics and utilities provide the per-meter interval usage data using the same watt-hour metrics
• Dispatch events are awarded/given in watts and later converted to watt-hours for performance calculations

Net, consumed, & generated interval data

• A value for energy_generated_wh indicates that within that interval this amount of energy was exported to the grid. It is possible that during that same interval, even more energy was consumed which would result in a positive energy_net_wh
• A negative energy_net_wh indicates that more energy was generated than consumed onsite, resulting in a negative net load and energy being exported back to the grid
• Not all utilities provide data broken down by consumed vs. generated in which case these would be 0

Negative performance

• This indicates that during a dispatch event when energy was supposed to be curtailed or reduced, load onsite was actually higher than the expected baseline load and therefore resulted in negative performance

Capacity performance and resource-level metrics

• These will be available via API in a future release