Historical Collection

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

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:
  • 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. 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).