Event Performance & Interval Data

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 performance and interval data API endpoints described in this guide.

Performance Endpoints

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 unresponsive meters endpoint provides event response summary and categorization for meter IDs in a requested month. Categorization includes: NEVER_RESPONDS, RARELY_RESPONDS, NORMALLY_RESPONDS, or NEW_METER.

Interval Data Endpoints

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:
- Flag unresponsive and poor performing meters for follow-up investigation
- Track and analyze performance per meter, customer, market, or region and look for trends
- 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

Request Parameter Considerations

For the event performance and interval data endpoints, 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:

Constraint	Explanation	Solution
Max 31 day date range (all endpoints)	The time between `date_range_start` and `date_range_end` cannot be more than 31 days	Make multiple requests on a month-by-month basis
Max 1 million data points in response (interval data endpoints only)	A data point is one interval object within the `intervals` array. E.g. querying 31 days (2976 15-min intervals) of data for 336 meters would fall within this limit but 337 meters would be over this threshold.	Reduce the number of meters or the number of days you are querying for if you hit this error

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.

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 on the event performance and interval data endpoints include:

Response Body Error	Resolution
“The difference between date_range_start and date_range_end cannot be more than 31 days”	Resolve this error by querying on a month-by-month basis
Your request would have surpassed the maximum amount of data points which is 1000000”	Resolve this error by reducing the number days and/or number of meters queried

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
        }
      ]
    }
  ]
}