Skip to main content
POST
/
organizations
/
{orgId}
/
usage
/
query
Query and filter usage data
curl --request POST \
  --url https://api.m3ter.com/organizations/{orgId}/usage/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "startDate": "2023-11-07T05:31:56Z",
  "endDate": "2023-11-07T05:31:56Z",
  "meterIds": [
    "<string>"
  ],
  "accountIds": [
    "<string>"
  ],
  "dimensionFilters": [
    {
      "meterId": "<string>",
      "fieldCode": "<string>",
      "values": [
        "<string>"
      ]
    }
  ],
  "aggregations": [
    {
      "meterId": "<string>",
      "fieldCode": "<string>",
      "fieldType": "DIMENSION",
      "function": "SUM"
    }
  ],
  "groups": [
    {
      "groupType": "ACCOUNT"
    }
  ],
  "limit": 10000
}
'
{
  "data": [
    {}
  ],
  "hasMoreData": true
}

Authorizations

​
Authorization
string
header
required

m3ter supports machine to machine authentication using the clientCredentials OAuth2 flow.

The authorizationCode flow controls access for human users via the m3ter Console application.

Path Parameters

​
orgId
string
required

UUID of the Organization. The Organization represents your company as a direct customer of the m3ter service.

Body

application/json
​
startDate
string<date-time>

The inclusive start date to define a time period to filter by. (ISO 8601 formatted)

​
endDate
string<date-time>

The exclusive end date to define a time period to filter by. (ISO 8601 formatted)

​
meterIds
string[]

Specify the Meters you want the query to return usage data for.

​
accountIds
string[]

Specify the Accounts you want the query to return usage data for.

​
dimensionFilters
object[]

Define Dimension filters you want to apply for the query.

Specify values for Dimension data fields on included Meters. Only data that match the specified Dimension field values will be returned for the query.

​
aggregations
object[]

Define the Aggregation functions you want to apply to data fields on included Meters:

  • SUM. Adds the values.
  • MIN. Uses the minimum value.
  • MAX. Uses the maximum value.
  • COUNT. Counts the number of values.
  • LATEST. Uses the most recent value.
  • MEAN. Uses the arithmetic mean of the values.
  • UNIQUE. Uses a count of the number of unique values.

NOTE! The Aggregation functions that can be applied depend on the data field type:

  • Measure fields. SUM, MIN, MAX, COUNT, LATEST, or MEAN functions can be applied.
  • Dimension field. COUNT or UNIQUE functions can be applied.
​
groups
object[]

If you've applied Aggregations for your query, specify any grouping you want to impose on the returned data:

  • Account
  • Time - group by frequency. Five options: DAY, HOUR, WEEK, MONTH, or QUARTER.
  • Dimension - group by Meter and data field.

NOTE: If you attempt to impose grouping for a query that doesn't apply Aggregations, you'll receive an error.

​
limit
integer<int32>

Define a limit for the number of usage data items you want the query to return, starting with the most recently received data item.

Required range: 1 <= x <= 20000

Response

Returns a list of usage data

​
data
object[]
​
hasMoreData
boolean

Boolean flag to indicate whether or not there are more data available for the query than are returned:

  • If there are more data, then TRUE.
  • If there are no more data, then FALSE.

NOTES:

  • The limit on the size of the return is 20000 data items. If the query returns more than this limit, only 20000 items are returned with most recent first and hasMoreData will be TRUE.
  • If you have set limit in your query request at fewer than the number returned by the query, then hasMoreData will be TRUE in the response.