Ongoing Monitoring

Ongoing monitoring is an easier, scheduled method of historical collection. This endpoint lets you bulk start and stop ongoing monitoring for Meters. Ongoing monitoring will automatically update the Meter's bills and intervals at the specified frequency. If the update interval is set to off, the specified Meters will stop ongoing monitoring.

A Meter's current ongoing monitoring settings can be found in its ongoing_monitoring attribute, which is an Ongoing Monitoring Object.


POST https://utilityapi.com/api/v2/meters/ongoing-monitoring
# Start ongoing monitoring on a monthly basis (and prepay for a year to get the 33% discount)
curl -X POST -H 'Authorization: Bearer API_TOKEN_HERE' \
    -d '{"meters": ["123", "234"], "frequency": "monthly", "prepay": "prepay_yearly"}' \
    'https://utilityapi.com/api/v2/meters/ongoing-monitoring'
# Stop ongoing monitoring
curl -X POST -H 'Authorization: Bearer API_TOKEN_HERE' \
    -d '{"meters": ["123", "234"], "frequency": "off"}' \
    'https://utilityapi.com/api/v2/meters/ongoing-monitoring'

The request body must be a valid JSON object. Below are the parameters that are required.

Parameter Format Description Example
meters List(UID String) A list of Meter uids for which to collect data. ["123", "234"]
frequency FrequencyType The frequency on which to monitor the meters. "monthly"
prepay PrepayType (Optional, defaults to "month_to_month") We offer a discount for paying for a year of monitoring up front. If you want to prepay for a year of monitoring, set this parameter to "prepay_yearly". "prepay_yearly"

Returns a Success object with an additional meters attribute with the meters that have had their monitoring status updated. Also included are the confirmed frequency and prepay attributes).

// Example result
{
    "success": true,
    "meters": ["123", "234"],
    "frequency": "daily",
    "prepay": "month_to_month"
}
Code Response Format Description
200 Success Successful request.
400 Error The POST body contains invalid parameters. Check the error in the response for the type of error:
  • required_param_missing - Missing the meters list.
  • invalid_param - Values in the meters list are invalid.
  • expired_or_revoked - All of the Authorizations for these meters are expired, so nothing can be collected.
We may add more error types in the future, so be able to handle unknown types.
401 Error Invalid or missing access_token. See our docs on Authentication for how to properly use your access_token.
402 Error Payment Required. Monitoring updates costs money, so you either need to have a positive balance or have a credit card on file. Go to your settings and add a credit card or pre-pay for data collections.
404 Error None of the Meters exist or you don't have permissions to see them.
429 N/A The request was rate limited. Check the Retry-After response header for how long to wait until retrying the request. Do not expect any specific response format for this error (could be html, json, or nothing).
500 N/A Internal server error. Do not expect any specific response format for this error (could be html, json, or nothing). This error is logged and will be fixed by our engineers.
503 N/A Site is currently down for maintenance. Do not expect any specific response format for this error (could be html, json, or nothing).
504 N/A We tried to build this request but timed out. Please try again later. Do not expect any specific response format for this error (could be html, json, or nothing).

Ongoing Monitoring Object

This is the object that contains the current ongoing monitoring settings for a Meter, including how frequently we will collect data for the Meter, and how you are setup to be charged for that ongoing scheduled data collection. You can find this object in any Meter's ongoing_monitoring attribute.

// daily monitoring (prepaid yearly)
{
    "frequency": "daily",
    "prepay": "prepay_yearly",
    "next_prepay": "2018-01-01T12:30:24.653422+00:00",
    "next_refresh": "2017-04-03T18:28:33.347382+00:00"
}
// stopped monitoring
{
    "frequency": "off",
    "prepay": null,
    "next_prepay": null,
    "next_refresh": null
}
Attribute Format Description Example
frequency FrequencyType The frequency on which to monitor the Meter. "monthly"
prepay PrepayType or null Whether ongoing monitoring is prepaid yearly (to receive a discounted rate), month-to-month (no discount), or null (when monitoring is off). "month_to_month"
next_prepay ISO8601 or null The timestamp of next prepay. Will be null if there is no next prepay (e.g. if frequency is off). "2020-01-01T12:30:24.653422+00:00"
next_refresh ISO8601 or null The timestamp of next expected refresh (see scheduling notes). Will be null if there is no next refresh scheduled (e.g. if frequency is off). "2019-01-01T08:30:24.653422+00:00"
 Extensible: We may extend this object type in the future, so be able to handle unknown attributes gracefully.

When starting ongoing monitoring, you can set how often you want us to go collect any new Bills and Intervals.

Type Description Notes
monthly Refresh data on a monthly basis. If we have previously collected bills for these Meters, we will attempt to proactively refresh within a few days of the monthly billing cycle. We continually optimize the timing of monthly updates to ensure you get new bill data promptly.
weekly Refresh data on a weekly basis. By default we schedule the update weekly from when monitoring was started. Occasionally, if that day of the week is consistently not successful at collecting data, we may shift the day of the week or time of day of the monitoring update.
daily Refresh data on a daily basis. We usually schedule daily updates overnight to optimize chances of success. When utility access is not available (e.g. when they are down for maintenance), we may shift the time of day of the monitoring update.
off Do not refresh data. By default, Meters are not set to refresh automatically, so this is the frequency you will see by default in the Meter object. Also, if you had previously started ongoing monitoring and want to turn it off for a meter, use this types.
 Extensible: We may add variants to this enumeration type in the future, so be able to handle unknown values gracefully.

When starting ongoing monitoring, you choose to pay more up front for monitoring to receive a discount. If you are not currently monitoring or turn off monitoring for the Meter (i.e. monitoring frequency is off), then this prepay type will be automatically set to null. To see when your next prepayment will occur, check the Meter's ongoing_monitoring.next_prepay value.

Type Description Notes
month_to_month Prepay for one month of monitoring. We will deduct the cost of one month of monitoring up front, then when the month of monitoring finishes, we will automatically deduct the cost for a new month of monitoring. If you want to stop charges at any point, simply update the monitoring frequency to off, and prepay will automatically switch to null. You can also upgrade to prepay yearly (to receive the discount) by submitting the meter again with the monitoring prepay type set accordingly.
prepay_yearly Prepay for one year of monitoring. We will deduct the cost of one year of monitoring up front (which includes a 33% discount) then when the month of monitoring finishes, we will automatically deduct the cost for a new year of monitoring (again at the discounted rate). If you want to stop charges or switch to month-to-month, simply update the ongoing monitoring frequency or prepay types. NOTE: We do not credit unused prepaid time when turning off monitoring or switching to month-to-month.
 Extensible: We may add variants to this enumeration type in the future, so be able to handle unknown values gracefully.