Historical Collection

Trigger a historical data collection for one or more Meters. If the meters have never been activated before, we will attempt to collect data for the number of months you specify for those meters. If you do not specify a number of months, the default is 12 months for customers on per month of data plans. For customers on per collection plans the default is 36 months. If the meters have had data collected previously, and you want to refresh the data, this will trigger a historical collection for the missing timespan. After you trigger a historical collection, the Meters 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
# As many meters are you like from multiple authorizations can be bundled into a single request.
curl -X POST -H 'Authorization: Bearer API_TOKEN_HERE' \
    -d '{"meters": ["123", "234"], "collection_duration": 12}' \
    'https://utilityapi.com/api/v2/meters/historical-collection'

NOTE: If you need to collect data for multiple meters, it is recommended that you bundle meters together in your requests to ensure prompt data delivery. This endpoint is built to handle large volumes of meters across authorizations and utilities, and handles the bundling and batching of jobs together per-request. Please ensure you are adhering to our rate-limits.

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. They do not have to all belong to the same authorization.	`["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 12 months for customers with per month of data plans. For customers with per collection plans, 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).

Documentation

API Endpoints