Listing Intervals

Get a list of Intervals, ordered by latest_first. Use at least one Meter or Authorization filter parameter. Unfortunately, getting a list of all intervals for every Meter is usually too resource intensive, so we return an error if you try to request intervals without an authorizations or meters query parameter.


GET https://utilityapi.com/api/v2/intervals
# Get a list of all a meter's intervals
curl -H 'Authorization: Bearer API_TOKEN_HERE' \
    'https://utilityapi.com/api/v2/intervals?meters=123'
# Get a year's worth of intervals for all meters under an authorization
curl -H 'Authorization: Bearer API_TOKEN_HERE' \
    'https://utilityapi.com/api/v2/intervals?authorizations=222&start=2015-01-01&end=2015-12-31'
# Get the latest intervals for a meter
curl -H 'Authorization: Bearer API_TOKEN_HERE' \
    'https://utilityapi.com/api/v2/intervals?meters=222&limit=1&order=latest_first'

Use at least one Meter or Authorization filter parameter. Unfortunately, getting a list of all intervals for every Meter is usually too resource intensive, so we return an error if you try to request intervals without an authorizations or meters query parameter.

Parameter Format Description Example
authorizations List(UID String) Filter by Authorization uids. Separate with commas (,). authorizations=123,456
meters List(UID String) Filter by Meter uids. Separate with commas (,). meters=123,456
start ISO8601 or YYYY-MM-DD Filter intervals that start on or after this date. Can be either a full ISO8601 timestamp or a short date (YYYY-MM-DD). If a short date, the local timezone of the utility for each result is used. start=2015-01-01
end ISO8601 or YYYY-MM-DD Filter intervals that end on or before this date. Can be either a full ISO8601 timestamp or a short date (YYYY-MM-DD). If a short date, the local timezone of the utility for each result is used. end=2015-12-31
limit Integer Limit results to a specific number of Interval objects. NOTE: This limits the number of Interval objects, not the number of interval readings inside the interval readings inside the Interval Readings Block. limit=12
order String Order results by earliest_first or latest_first (default is latest_first). order=earliest_first
allow_mixed Boolean Whether or not to allow mixed duration intervals in the response. The default is to only show intervals of the dominant duration. allow_mixed=false
after String A token representing the point to continue from on the next page of items. after=456

Returns a IntervalListing object containing a list of Interval objects. If the number of results is over 1000, a next parameter will have the link to the next in the series of lists.

// Example result
{
    "intervals": [
        {"uid": "12837438", "created": ...},
        {"uid": "12837438", "created": ...},
        ...
    ],
    "next": null,
}

This is the object that contains the Interval results for the request. We don't just return a straight list of results so that we can paginate results if needed. Currently, the maximum results per request is set at 1000.

Parameter Format Description Example
intervals List(Interval) List of Interval results. [{"uid": ...}, ...]
next URL or null If there are more results than the page limit, this is a link to the next set of results. "https://utilityapi.com/api/v2/intervals?meters=2456&after=234"
// Example IntervalListing
{
    "intervals": [...],
    "next": null,
}
Code Response Format Description
200 IntervalListing Successful request.
202 Empty Request is too large to be synchronous, so building a cache asynchronously. See Retry-After header for how long to wait before trying again.
400 Error The query parameters included are malformed. Check the error in the response for the type of error:
  • invalid_param - One of the query parameters was invalid. Check the error description for more info.
  • ... - 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.
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).