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" |
revoked != null
) or
expired
(i.e. expires <= now
) are silently ignored in the
meters
list. If all Meters in the list are revoked or expired,
we will return a 400 response.
You can figure out which meters have been ignored by comparing
your POST body meters
list and the response's
meters
list. We silently drop so you don't have to check
the revoke or expiration status of every meter every time you want to
monitor your meters.
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:
|
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). |
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.
status_ts
attribute. To see when the next monitoring update is scheduled, check the Meter's
ongoing_monitoring.next_refresh
note.
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. |