Trigger a historical data collection for Meters.
If the meter has never been activated before, we will attempt to collect at least 13
months of historical billing and interval data for that Meter. If the meter has had
data collected previously, and you want to refresh the data, this will trigger a historical
collection for the missing timespan. After trigger a historical collection the Meter
status
will usually be set to "pending"
since a job will be
running to go and collect data for those Meters.
POST https://utilityapi.com/api/v2/meters/historical-collection
# Trigger a historical collection for two meters curl -X POST -H 'Authorization: Bearer API_TOKEN_HERE' \ -d '{"meters": ["123", "234"]}' \ 'https://utilityapi.com/api/v2/meters/historical-collection'
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"] |
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
collect historical data.
Returns a Success object
with an additional meters
attribute with the meters that have
triggered for a historical collection.
// Example result { "success": true, "meters": ["123", "234"] }
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. Collecting data costs money, so you MUST have a positive balance. There is no way to pay using the API, so go to your settings and select a pre-pay for data collections. For free and demo meters, you shouldn't see this response code. |
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). |