---
title: "Query meter"
method: POST
path: "/api/v1/meters/{meterIdOrSlug}/query"
tags: ["Meters"]
---

# Query meter

`POST /api/v1/meters/{meterIdOrSlug}/query`

## Path parameters

- `meterIdOrSlug` string, required

## Request body

- MeterQueryRequest — A meter query request.
  - `clientId` string — Client ID Useful to track progress of a query.
  - `from` string, date-time — Start date-time in RFC 3339 format. Inclusive.
  - `to` string, date-time — End date-time in RFC 3339 format. Inclusive.
  - `windowSize` 'MINUTE' | 'HOUR' | 'DAY' | 'MONTH' — Aggregation window size.
  - `windowTimeZone` string — The value is the name of the time zone as defined in the IANA Time Zone Database (http://www.iana.org/time-zones). If not specified, the UTC timezone will be used.
  - `subject` string[] — Filtering by multiple subjects.
  - `filterCustomerId` string[] — Filtering by multiple customers.
  - `filterGroupBy` object — Simple filter for group bys with exact match.
  - `advancedMeterGroupByFilters` object — Optional advanced meter group by filters. You can use this to filter for values of the meter groupBy fields.
  - `groupBy` string[] — If not specified a single aggregate will be returned for each subject and time window. `subject` is a reserved group by value.

## Response `200`

The request has succeeded.

- MeterQueryResult — The result of a meter query.
  - `from` string, date-time — The start of the period the usage is queried from. If not specified, the usage is queried from the beginning of time.
  - `to` string, date-time — The end of the period the usage is queried to. If not specified, the usage is queried up to the current time.
  - `windowSize` 'MINUTE' | 'HOUR' | 'DAY' | 'MONTH' — Aggregation window size.
  - `data` MeterQueryRow[], required — The usage data. If no data is available, an empty array is returned.
    - `value` number, double, required — The aggregated value.
    - `windowStart` string, date-time, required — The start of the window the value is aggregated over.
    - `windowEnd` string, date-time, required — The end of the window the value is aggregated over.
    - `subject` string, nullable, required — The subject the value is aggregated over. If not specified, the value is aggregated over all subjects.
    - `customerId` string — The customer ID the value is aggregated over.
    - `groupBy` object, required — The group by values the value is aggregated over.

## Other responses

- `400` — The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
- `401` — The request has not been applied because it lacks valid authentication credentials for the target resource.
- `403` — The server understood the request but refuses to authorize it.
- `404` — The origin server did not find a current representation for the target resource or is not willing to disclose that one exists.
- `412` — One or more conditions given in the request header fields evaluated to false when tested on the server.
- `500` — The server encountered an unexpected condition that prevented it from fulfilling the request.
- `503` — The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.
- `default` — An unexpected error response.

---

[API](https://skmtc.net/openmeterio/apis/openmeter-api.md) · [All operations](https://skmtc.net/openmeterio/apis/openmeter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openmeterio/openmeter-api/revisions/1cd97f063f4a/schema)