Sign in

v51

latestOpenAPI 3.0.0Apache 2.0raw.githubusercontent.com2026-08-011534301009.2 KB
Meters

Query meter

post/api/v1/meters/{meterIdOrSlug}/query

Path parameters

meterIdOrSlugstring required

Request body

clientIdstring

Client ID Useful to track progress of a query.

fromstring date-time

Start date-time in RFC 3339 format.

Inclusive.

tostring date-time

End date-time in RFC 3339 format.

Inclusive.

windowSize'MINUTE' | 'HOUR' | 'DAY' | 'MONTH'

Aggregation window size.

windowTimeZonestring

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.

subjectstring[]

Filtering by multiple subjects.

filterCustomerIdstring[]

Filtering by multiple customers.

filterGroupByobject

Simple filter for group bys with exact match.

advancedMeterGroupByFiltersobject

Optional advanced meter group by filters. You can use this to filter for values of the meter groupBy fields.

groupBystring[]

If not specified a single aggregate will be returned for each subject and time window. subject is a reserved group by value.

Example request

{
  "clientId": "f74e58ed-94ce-4041-ae06-cf45420451a3",
  "from": "2023-01-01T01:01:01.001Z",
  "to": "2023-01-01T01:01:01.001Z",
  "windowTimeZone": "UTC",
  "subject": [
    "subject-1",
    "subject-2"
  ],
  "filterCustomerId": [
    "id-1",
    "id-2"
  ],
  "filterGroupBy": {
    "model": [
      "gpt-4-turbo",
      "gpt-4o"
    ],
    "type": [
      "prompt"
    ]
  },
  "advancedMeterGroupByFilters": {
    "model": {
      "$in": [
        "gpt-4",
        "gpt-4o"
      ]
    },
    "type": {
      "$eq": "input"
    }
  },
  "groupBy": [
    "model",
    "type"
  ]
}

Response

The request has succeeded.

fromstring date-time

The start of the period the usage is queried from. If not specified, the usage is queried from the beginning of time.

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

Example response

{
  "from": "2023-01-01T00:00:00Z",
  "to": "2023-01-02T00:00:00Z",
  "windowSize": "DAY",
  "data": [
    {
      "value": 12,
      "windowStart": "2023-01-01T00:00:00Z",
      "windowEnd": "2023-01-02T00:00:00Z",
      "subject": "customer-1",
      "groupBy": {
        "model": "gpt-4-turbo",
        "type": "prompt"
      }
    }
  ]
}