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.

HTTP Request

POST https://utilityapi.com/api/v2/meters/historical-collection

Examples

# Trigger a historical collection for two meters with an optional duration range in months
curl -X POST -H 'Authorization: Bearer API_TOKEN_HERE' \
    -d '{"meters": ["123", "234"], "collection_duration": 12}' \
    'https://utilityapi.com/api/v2/meters/historical-collection'

POST Body

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"]`
`collection_duration`	Integer	The duration in months for which to collect data. The valid range is from 1-36 months. This is optional. The default is 36 months.	`12`

NOTE: Meters that are revoked (i.e. 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.

Response

Returns a Success object with an additional meters attribute with the meters that have triggered for a historical collection. It also includes an optional collection_duration attribute, indicating the requested number of months for the collection period.

// Example result
{
    "success": true,
    "meters": ["123", "234"],
    "collection_duration": 12
}

HTTP Response Codes

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